MCP server

Endpoint & transport

https://<your-api-url>/mcp

Authorization: Bearer rly_live_…

Because the server is stateless, there's no session to keep alive and no reconnect dance: every request is independently authenticated and independently isolated. Clients that only speak the deprecated HTTP+SSE transport, or that can't send a custom header, need the mcp-remote bridge shown under Claude apps below.

Connect a client

Create a key at API keys first — it's shown once. Every snippet below assumes it's in $RELAY_API_KEY.

Claude Code

claude mcp add --transport http relay https://<your-api-url>/mcp \
  --header "Authorization: Bearer $RELAY_API_KEY"

claude mcp list          # should report: relay ✔ Connected

Claude apps (claude.ai and Claude Desktop)

Add Relay as a custom connector: Settings → Connectors → Add custom connector, paste the endpoint URL, and put Bearer $RELAY_API_KEY in the request-header field. Header authentication for custom connectors is rolling out gradually; if your account doesn't have it, use the local bridge below instead.

{
  "mcpServers": {
    "relay": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://<your-api-url>/mcp",
        "--header", "Authorization: Bearer ${RELAY_API_KEY}"
      ],
      "env": { "RELAY_API_KEY": "rly_live_…" }
    }
  }
}

Cursor

{
  "mcpServers": {
    "relay": {
      "url": "https://<your-api-url>/mcp",
      "headers": { "Authorization": "Bearer rly_live_…" }
    }
  }
}

VS Code

Put this in .vscode/mcp.json — VS Code prompts for the key on first use and keeps it out of the file. Headers set in a workspace .mcp.json are ignored, so use .vscode/mcp.json.

{
  "inputs": [
    { "type": "promptString", "id": "relay-key", "description": "Relay API key", "password": true }
  ],
  "servers": {
    "relay": {
      "type": "http",
      "url": "https://<your-api-url>/mcp",
      "headers": { "Authorization": "Bearer ${input:relay-key}" }
    }
  }
}

Any other MCP client

{
  "mcpServers": {
    "relay": {
      "type": "streamable-http",
      "url": "https://<your-api-url>/mcp",
      "headers": { "Authorization": "Bearer rly_live_…" }
    }
  }
}

Verify it by hand

Because the server is stateless, you can list tools with one request — no initialize handshake required. Responses come back as a server-sent event stream.

curl -N -X POST https://<your-api-url>/mcp \
  -H "Authorization: Bearer $RELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

For interactive debugging, point the official inspector at the same URL: npx @modelcontextprotocol/inspector.

Tool reference

8 tools. Each declares a JSON Schema for its input and its output, so clients validate structured results rather than parsing prose.

Behavior annotations

Every tool states all four MCP behavior hints explicitly. The protocol's defaults are pessimistic — an unannotated tool is assumed to be a destructive, non-idempotent write — so declaring them lets a client run the reads unattended and save confirmation prompts for the one tool that deserves it.

Results & errors

Every tool returns both a JSON text block and structuredContent matching its declared output schema — so a client can render the text and a program can read the fields.

{
  "content": [{ "type": "text", "text": "{ \"post\": { … } }" }],
  "structuredContent": {
    "post": { "id": "3f0c…", "status": "scheduled", "targets": [ … ] }
  }
}

• Domain errors — an unknown account ID, a caption over 2,200 characters, the wrong media count for a post type — come back as a tool result with isError: true and a human-readable message. The agent can read the message and fix the call itself.
• Authentication failures are HTTP 401 on the transport, before any tool runs.
• Rate limits are HTTP 429 with Retry-After — the same 120 requests/minute per key as the REST API, counted per MCP request.
• Publish failures are never tool errors. post_create succeeds as soon as the post is queued; Instagram's verdict arrives later on the target timeline, so the agent must call post_status to know the outcome.

Agent workflow

The path that works, in order:

auth_status        → confirm the key works and something is connected
accounts_list      → resolve a handle like "@northlight.co" to an account id
media_upload       → optional: store a file once, reuse it across posts
post_create        → queue the post (targets + caption + media [+ schedule_at])
post_status        → poll until every target is published or failed

• Never guess an account ID or a post ID — resolve them with accounts_list and posts_list.
• Scheduling is not instant publishing: post_create without schedule_at still goes out on the next scheduler tick, within a minute.
• After creating a post, wait ~30 seconds before the first post_status call. Video takes longer than images — minutes, not seconds.
• Confirm with the user before post_cancel, and before publishing anything without an explicit schedule.

Prompts to try

Posts an agent creates are tagged source: "mcp", so they're easy to spot in the dashboard and in GET https://<your-api-url>/v1/posts.