Connect an MCP client

Add Lucra as a custom server

Create a key in Settings → API and MCP, then enter these values in your client's Custom MCP server form:

If the client has a dedicated token field, paste only the key. Do not add Bearer yourself. If it asks for custom headers instead, add Authorization: Bearer <your Lucra API key>.

You do not need a command, npm package, stdio configuration, OAuth client ID, client secret, callback URL, or the REST API base URL.

Choose the right scopes

Every MCP key needs mcp:tools:read so the client can discover tools. Add mcp:tools:call to run them, plus the business scopes for the Lucra data or actions you want to expose.

For example, a read-only program key needs mcp:tools:read, mcp:tools:call, and brand:programs:read or partner:programs:read.

Agency keys can operate on the agency's own workspace or an allowed client. Pass the client's workspace slug in the tool's client argument when acting for a client.

Confirm the connection

Save the server and ask the client to list Lucra's tools. A successful connection shows only the tools allowed by that key's scopes.

For local development, use http://127.0.0.1:8787/mcp and a key issued by the same local environment.

Generic configuration

{
  "mcpServers": {
    "lucra": {
      "type": "http",
      "url": "https://api.onlucra.com/mcp",
      "headers": {
        "Authorization": "Bearer <your Lucra API key>"
      }
    }
  }
}

Exact configuration keys vary by client. Do not add custom headers when your client already has a separate Bearer token field.

Protocol details

Lucra supports only the current 2026-07-28 MCP protocol over stateless Streamable HTTP. Current clients use server/discover; there is no initialize request or session ID.

MCP clients normally add the protocol headers and request metadata automatically. This complete request is useful when testing the server directly:

curl -X POST https://api.onlucra.com/mcp \
  -H "Authorization: Bearer $LUCRA_API_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: server/discover" \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{},"io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1.0.0"}}}}'

For tools/call, clients also send Mcp-Name with the same tool name as params.name. GET /mcp is not supported.

Requests with an Origin outside Lucra's configured allowlist are rejected with 403 invalid_origin. The server does not issue MCP session IDs; each POST is independently authenticated.

The unauthenticated catalog at GET /v1/mcp/tools includes tool annotations, input schemas, output schemas, and required scope alternatives.

Troubleshooting