MCP Authentication

The MCP server requires authentication for all operations. It uses the same auth system as the GraphQL API: API keys or JWT.

Sending Credentials

Include credentials in every request using one of these headers:

x-api-key: lf_live_YOUR_KEY

or

Authorization: Bearer lf_live_YOUR_KEY

Both are equivalent. The x-api-key header takes precedence if both are present.

How Auth Works

Auth is resolved per-request — there is no persistent MCP session auth state. Each JSON-RPC call checks the header independently.

1. x-api-key: lf_live_... — API key lookup, resolved to a user identity.
2. Authorization: Bearer lf_live_... — same as above.
3. Authorization: Bearer <jwt> — JWT verification, resolved to user identity.

The auth middleware sets req.auth with userId, apiKeyId, and extra fields for the MCP SDK handlers.

Unauthorized Response

If no valid credential is provided, the server returns:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Unauthorized. Provide x-api-key or Authorization: Bearer header."
  },
  "id": null
}

HTTP status code: 401 Unauthorized.

Revoked Keys

Revoked API keys are invalid immediately. Requests with a revoked key receive 401 with an "Unknown API key" error message.

Rate Limiting

Per-key rate limiting applies to MCP requests: 120 req/min per API key, shared with the GraphQL API bucket.

Exceeding the limit returns:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32001,
    "message": "Too many requests. Rate limit exceeded."
  },
  "id": null
}

Per-Request Auth (Not Session-Scoped)

Each JSON-RPC call is authenticated independently. The session (Mcp-Session-Id) tracks transport state only — it does not hold auth. You can rotate API keys mid-session simply by changing the header on the next request.

Best Practices

• Rotate keys periodically from the lnkify dashboard.
• Use separate keys per client or environment (development, production, each AI tool).
• Never embed keys in client-side code or public repositories.

Next: Tools