PENDINGAWAITING LINK
--:--:--▌
Guide · Model Context Protocol

How to connect Claude Desktop and Cursor to NATS via MCP

The Kannaka Command Center exposes the live NATS swarm — subjects, memories, agent heartbeats, OODA cycles — as an MCP server. This guide walks through configuring Claude Desktop, Cursor, and ChatGPT to talk to it, and shows how the underlying Model Context Protocol transports the calls.

What is MCP?

The Model Context Protocol (MCP) is an open JSON-RPC standard published by Anthropic in late 2024. It defines how a client (an AI assistant) discovers and invokes tools, reads resources, and runs prompts hosted on a remote server. Think of it as LSP for AI tool calls: one wire format, many clients, many servers.

Kannaka's MCP server lives at https://nats.ninja-portal.com/mcp and speaks the Streamable HTTP transport. It authenticates via OAuth 2.1 (interactive) or client_credentials (machine-to-machine).

1. Provision access

For an interactive user (Claude Desktop, Cursor): no setup required — the clients handle OAuth on first use.

For an autonomous agent or CI job: open the Integrations page and create an agent client. You'll receive a client_id and one-time client_secret scoped to mcp:read, mcp:capture, and mcp:recall.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d 'grant_type=client_credentials&scope=mcp:read mcp:recall' \
  https://nats.ninja-portal.com/api/public/auth/agent/token
2. Connect Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "kannaka": {
      "url": "https://nats.ninja-portal.com/mcp"
    }
  }
}

Restart Claude Desktop. On the first tool call, Claude opens a browser to complete OAuth against the Kannaka authorization server. Approve the consent screen and the server appears in Claude's tool tray with the badge kannaka.

3. Connect Cursor

In Cursor: Settings → MCP → Add new server. Set transport to HTTP and paste the URL:

Name: kannaka
URL:  https://nats.ninja-portal.com/mcp

Cursor performs the OAuth dance in a popup. Once green, the tools are available in Composer and the Cursor agent.

4. Connect ChatGPT / custom clients

ChatGPT's Developer Mode supports MCP over HTTP with OAuth. Add the same URL under Settings → Connectors → Add connector. For any custom SDK, point at the same endpoint and send:

POST /mcp HTTP/1.1
Host: nats.ninja-portal.com
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json, text/event-stream

The Accept: text/event-stream header is mandatory — MCP servers return 406 without it.

5. Verify

Ask the assistant: "Call whoami on the kannaka server". You should see the authenticated principal and scopes. Then try "List the top NATS subjects" to invoke list_subjects.

{
  "principal": "user_01H...",
  "scopes": ["mcp:read", "mcp:recall"],
  "server": "kannaka-command-center"
}
Tool reference
  • list_subjects — enumerate the discovered NATS subject space with message counts and last-seen timestamps.
  • whoami — return the caller's principal and scopes.
  • capture_messages — subscribe to a subject for N seconds and return the buffered payloads.
  • query_messages — search recent captures by subject prefix and payload keyword.
  • recall — issue a request/reply against KANNAKA.recall.kannaka-prime to warm the memory cortex.
Troubleshooting
  • 406 Not Acceptable — the client isn't sending Accept: text/event-stream. Update to a recent MCP SDK.
  • 401 invalid_client — the client secret is wrong or revoked. Rotate on the Integrations page.
  • OAuth loop in Claude — clear ~/Library/Application Support/Claude/mcp-auth/ and restart.
  • Tools missing — run the diagnostics panel on /integrations to inspect JWKS, audience, and MCP init failures.