Skip to content

MCP server

Connect Claude, Cursor, and other MCP clients to your API.

Snaapi exposes a built-in Model Context Protocol server so that LLM-powered clients (Claude Desktop, Claude Code, Cursor, the official MCP Inspector, and any other Streamable HTTP client) can read your OpenAPI specs and call your APIs as tools, with the same authentication, authorization, and validation as a normal HTTP request.

This guide walks through connecting a few popular clients to a hosted Snaapi API.

Before you start

Fill in the two placeholders below. They are used everywhere in this document.

Placeholder Where to find it Example
<API_NAME> The subdomain of your API on Snaapi Cloud. The MCP endpoint lives at https://<API_NAME>.snaapi.cloud/mcp. acme-prod
<BEARER_TOKEN> An API key issued from the console. See Issuing a token. sna_...

Throughout this document, replace <API_NAME> and <BEARER_TOKEN> with your real values.

Issuing a token

  1. Sign in to the console.
  2. Pick the API you want to connect (the one served at https://<API_NAME>.snaapi.cloud).
  3. Open the API Keys tab.
  4. Click New API key, give it a label (for example, claude-desktop), and pick a role. The role determines which tools the client will see (admin keys see internal admin tools; user keys see only the resource CRUD tools their role permits).
  5. Copy the generated token. It is only shown once. This is your <BEARER_TOKEN>.

The MCP server applies your role's RBAC to every call. If a tool returns 401 UNAUTHORIZED or 403 FORBIDDEN, the LLM is being told (truthfully) that your token is not allowed to perform that action.

What's exposed over MCP

Once connected, your client will see:

  • Resource tools. One set of five tools per enabled resource: resource.<name>.list, .get, .create, .update, .delete. Inputs and outputs use the JSON:API envelope ({ data: { type, id?, attributes } }).
  • Internal admin tools. One tool per route under /v1/_* (registry, users, roles, webhooks, etc.). Only visible to admin tokens. Names follow <tag>.<segments>.<action>, e.g., registry.resources.list, users.create, webhooks.update.
  • OpenAPI resources. Two MCP resources:
    • openapi://snaapi/public. The public OpenAPI spec (mirrors GET /openapi.json).
    • openapi://snaapi/full. The full spec including internal admin paths (mirrors GET /openapi.json?registry=true).

The tool set is rebuilt on every request, so resources you create through the console show up to the LLM immediately. No client restart required.

Claude.ai (Custom Connectors)

Claude.ai supports remote MCP servers via the Custom Connectors feature, with full OAuth-based sign-in.

  1. Open https://claude.ai/settings/connectors.
  2. Click Add custom connector.
  3. Fill in:
    • Name: Snaapi (<API_NAME>)
    • Remote MCP server URL: https://<API_NAME>.snaapi.cloud/mcp
    • Leave the Advanced settings blank. The connector will detect the WWW-Authenticate challenge from /mcp and start the OAuth flow.
  4. Click Connect. Claude.ai will open a browser window for you to sign in with your Snaapi account and approve consent.
  5. Sign in with a Snaapi user whose role is allowed to call the tools you intend to use. The role's RBAC applies to every tool call.

After connecting, ask Claude something like:

List my widgets.

Claude will call resource.widgets.list and return the result.

Claude Desktop

Claude Desktop supports remote MCP servers via the same Custom Connectors feature. Use it for a static bearer token instead of the OAuth flow.

  1. Open Claude Desktop, then Settings, then Connectors.
  2. Click Add custom connector.
  3. Fill in:
    • Name: Snaapi (<API_NAME>)
    • Remote MCP server URL: https://<API_NAME>.snaapi.cloud/mcp
  4. Click Advanced settings and add a custom HTTP header:
    • Header name: Authorization
    • Header value: Bearer <BEARER_TOKEN>
  5. Save. Claude Desktop will connect and enumerate the available tools.

Claude Code

Claude Code is Anthropic's official CLI. Add your Snaapi MCP server with one command.

claude mcp add --transport http snaapi \
  https://<API_NAME>.snaapi.cloud/mcp \
  --header "Authorization: Bearer <BEARER_TOKEN>"

Or edit ~/.claude/mcp.json directly and add:

{
  "mcpServers": {
    "snaapi": {
      "transport": "http",
      "url": "https://<API_NAME>.snaapi.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <BEARER_TOKEN>"
      }
    }
  }
}

Restart claude (or run /mcp in an active session) and you will see the snaapi server listed.

Cursor

Cursor supports remote MCP servers via the ~/.cursor/mcp.json config file (or project-local .cursor/mcp.json).

{
  "mcpServers": {
    "snaapi": {
      "url": "https://<API_NAME>.snaapi.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <BEARER_TOKEN>"
      }
    }
  }
}

Open Settings, then MCP, and confirm the server shows a green dot. Cursor will auto-detect that this is a Streamable HTTP endpoint.

MCP Inspector

The MCP Inspector is a browser-based debugger that is useful for exploring the tool list and trying calls by hand.

npx @modelcontextprotocol/inspector

In the UI:

  1. Transport Type: Streamable HTTP
  2. URL: https://<API_NAME>.snaapi.cloud/mcp
  3. Open Authentication and set:
    • Bearer Token: <BEARER_TOKEN>
  4. Click Connect.

You can now browse tools and resources, inspect their JSON Schemas, and fire test calls without an LLM in the loop.

Programmatic clients (TypeScript SDK)

If you are building your own integration, use the official @modelcontextprotocol/sdk package.

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://<API_NAME>.snaapi.cloud/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer <BEARER_TOKEN>",
      },
    },
  },
);

const client = new Client({ name: "my-app", version: "1.0.0" }, {});
await client.connect(transport);

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

await client.close();
await transport.close();

Curl quick check

To confirm the endpoint and your token before configuring a client, run a tools/list JSON-RPC request directly.

curl -sS https://<API_NAME>.snaapi.cloud/mcp \
  -H "Authorization: Bearer <BEARER_TOKEN>" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

You should see a streamed response containing a tools array. If you get 401 Unauthorized, your token is wrong or expired. If you get 406 Not Acceptable, you are missing the Accept header. The Streamable HTTP transport requires both application/json and text/event-stream.

Troubleshooting

Symptom Likely cause
401 UNAUTHORIZED on every call The bearer token is missing, malformed, or revoked. Re-issue from the console.
Tools list works, but resource.<name>.create returns 403 Your token's role does not have create permission on that resource. Adjust the role in the console under Roles.
Tools list works, but a resource you just created isn't listed Confirm the resource is enabled in the console. Disabled resources are intentionally hidden from MCP.
406 Not Acceptable from curl Add Accept: application/json, text/event-stream. Real MCP clients send this by default.
LLM calls a tool but reports the result as an error Inspect the isError flag and the embedded { status, data } payload. The MCP tool surfaces the underlying HTTP status verbatim.

Security notes

  • The bearer token grants the full set of permissions of the role it was issued under. Treat it like a password.
  • Rotate tokens from the console at any time. Old tokens stop working immediately.
  • The MCP server never bypasses authentication, RBAC, field-level access, or row-level access. Every tool call goes through the same middleware stack as the equivalent REST call.