> ## Documentation Index > Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Quickstart > Connect an agent to the Supernova MCP so it can act on a user's accounts. Supernova gives AI agents the tools to take any action on your users' online accounts, both actions that require user authentication and those that don't, such as searching for products, building a cart, and checking out. Your agent connects to the Supernova MCP server with an MCP token you create for each user. For actions requiring authentication, users link their accounts once and your agent can then take those actions. > [!NOTE] > > Supernova is in early access and runs in production only. [Join the waitlist](https://www.knotapi.com/supernova) to get access. ## Connection details | | | | - | - | | **Server URL** | `https://supernova-mcp.knotapi.com/mcp` | | **Transport** | Streamable HTTP | | **Authentication** | `Authorization: Bearer sn_prod_...` with an MCP token for one user | An MCP token acts as the one user you created it for. The agent can reach only that user's accounts and the sites enabled for your Knot account. ## 1. Get your API key In the [Knot Dashboard](https://dashboard.knotapi.com/developers/keys), retrieve your `client_id` and `secret` and base64 encode them to create your API key. Docs [here](https://docs.knotapi.com/api-reference/authentication.md) for further details. ## 2. Create an MCP token for a user From your backend, call [Create MCP Token](https://docs.knotapi.com/api-reference/mcp-tokens/create-mcp-token.md) with your `client_id` and `secret` as Basic auth. Supernova can perform both unauthenticated and authenticated (i.e. behind a login) actions online. To enable authenticated actions (recommended), providing the user's `phone_number` when creating the MCP token is required, so the Supernova MCP can create sign-in links. ```bash Request theme={"system"} curl --request POST \ --url https://production.knotapi.com/mcp/tokens/create \ --user "$KNOT_CLIENT_ID:$KNOT_SECRET" \ --header 'Content-Type: application/json' \ --data '{ "external_user_id": "123abc", "phone_number": "+12025550123", "expires_in": 86400 }' ``` ```json Response theme={"system"} { "token": "sn_prod_wyLZTDc3_HzXo5lcRkkbZpnmFfg5DU63nHnUsyPQbi0", "expires_at": "2026-10-27T15:30:00Z" } ``` The token acts for that one user. Keep your `client_id` and `secret` on your backend and give your agent only the MCP token. Tokens last 1 day by default and up to 30 days. Call [Revoke MCP Tokens](https://docs.knotapi.com/api-reference/mcp-tokens/revoke-mcp-tokens.md) to revoke all of a user's tokens. ## 3. Add the Supernova MCP to your agent Point your MCP client at `https://supernova-mcp.knotapi.com/mcp` over Streamable HTTP and send the MCP token in the `Authorization` header as `Bearer sn_prod_...`. #### Try it locally The fastest way to try Supernova is to add it to a coding agent on your machine. Save your [API key](#get-your-api-key) to your shell: ```bash Save your API key theme={"system"} case "$SHELL" in */zsh) f=~/.zshrc;; */bash) f=~/.bashrc;; *) f=~/.profile;; esac; touch "$f" \ && sed -i.bak '/^export KNOT_API_KEY=/d' "$f" && rm -f "$f.bak" \ && printf 'export KNOT_API_KEY=%s\n' '' >> "$f" && export KNOT_API_KEY='' ``` Then paste this prompt into your coding agent. It asks for your phone number, creates an MCP token, saves it to your shell, and adds the server: ```text Setup prompt expandable wrap theme={"system"} Set up the Supernova MCP server so you can act on my accounts at online sites. My Knot API key is in the KNOT_API_KEY environment variable. Use it only to create my MCP token below, and never print it or the token. 1. Ask me for my mobile number (US or Canada). Supernova texts it a code when I sign in to a site. 2. Create my MCP token: POST https://production.knotapi.com/mcp/tokens/create with the header "Authorization: Basic " and the body {"external_user_id": "", "phone_number": ""}. Save the token as SUPERNOVA_MCP_TOKEN in my shell profile, the same way KNOT_API_KEY is saved. It lasts 1 day; create a new one when it expires. 3. Add the MCP server https://supernova-mcp.knotapi.com/mcp (Streamable HTTP) to the client you're running in, named supernova, with the header "Authorization: Bearer ". Restart if the supernova tools don't load. 4. Call supernova_list_sites, tell me which sites I can use, and suggest a few tasks. 5. When a site needs me to sign in, send me the link Supernova returns. Never ask for my password or the code texted to me. Docs for agents: https://docs.knotapi.com/llms.txt ``` Or set `SUPERNOVA_MCP_TOKEN` to a token from step 2 and add the server yourself: > [tab] Claude Code > > ```bash theme={"system"} > claude mcp add --transport http supernova https://supernova-mcp.knotapi.com/mcp \ > --header "Authorization: Bearer $SUPERNOVA_MCP_TOKEN" > ``` > [tab] Codex > > Codex reads the token from `SUPERNOVA_MCP_TOKEN` each time it starts: > > ```bash theme={"system"} > codex mcp add supernova --url https://supernova-mcp.knotapi.com/mcp \ > --bearer-token-env-var SUPERNOVA_MCP_TOKEN > ``` > [tab] Cursor > > Add the server to `.cursor/mcp.json`: > > ```json theme={"system"} > { > "mcpServers": { > "supernova": { > "url": "https://supernova-mcp.knotapi.com/mcp", > "headers": { > "Authorization": "Bearer ${env:SUPERNOVA_MCP_TOKEN}" > } > } > } > } > ``` > [tab] VS Code > > Add the server to `.vscode/mcp.json`. VS Code asks for the token when it starts the server: > > ```json theme={"system"} > { > "inputs": [ > { > "type": "promptString", > "id": "supernova-mcp-token", > "description": "Supernova MCP token", > "password": true > } > ], > "servers": { > "supernova": { > "type": "http", > "url": "https://supernova-mcp.knotapi.com/mcp", > "headers": { > "Authorization": "Bearer ${input:supernova-mcp-token}" > } > } > } > } > ``` #### Add it to your deployment env When you're ready, connect the Supernova MCP to your user-facing agent, from the server where it runs. Your backend creates an MCP token for each user and passes it to your agent's MCP client. Create the token when the user starts a conversation, reuse it until its `expires_at`, and never send it to your client app. > [tab] Claude API > > The [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) connects Claude to Supernova from the Messages API: > > ```python expandable theme={"system"} > import anthropic > > client = anthropic.Anthropic() > > response = client.beta.messages.create( > model="claude-opus-5-5", > max_tokens=16000, > betas=["mcp-client-2025-11-20"], > mcp_servers=[ > { > "type": "url", > "url": "https://supernova-mcp.knotapi.com/mcp", > "name": "supernova", > "authorization_token": supernova_mcp_token, > } > ], > tools=[{"type": "mcp_toolset", "mcp_server_name": "supernova"}], > messages=[{"role": "user", "content": "Which of my merchant accounts are linked?"}], > ) > ``` > [tab] OpenAI API > > The [remote MCP tool](https://developers.openai.com/api/docs/guides/tools-connectors-mcp) connects OpenAI models to Supernova from the Responses API: > > ```python expandable theme={"system"} > from openai import OpenAI > > client = OpenAI() > > response = client.responses.create( > model="gpt-6-astra", > tools=[ > { > "type": "mcp", > "server_label": "supernova", > "server_url": "https://supernova-mcp.knotapi.com/mcp", > "authorization": supernova_mcp_token, > "require_approval": "never", > } > ], > input="Which of my merchant accounts are linked?", > ) > ``` > [tab] TypeScript > > With the [MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/v2/) (`@modelcontextprotocol/client`): > > ```typescript expandable theme={"system"} > import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'; > > const client = new Client({ name: 'my-agent', version: '1.0.0' }); > const transport = new StreamableHTTPClientTransport(new URL('https://supernova-mcp.knotapi.com/mcp'), { > requestInit: { headers: { Authorization: `Bearer ${supernovaMcpToken}` } }, > }); > await client.connect(transport); > > const { tools } = await client.listTools(); > const result = await client.callTool({ name: 'supernova_list_accounts', arguments: {} }); > console.log(result.structuredContent); > > await client.close(); > ``` > [tab] Python > > With the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (`mcp`): > > ```python expandable theme={"system"} > from mcp import Client > from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client > > http_client = create_mcp_http_client(headers={"Authorization": f"Bearer {supernova_mcp_token}"}) > transport = streamable_http_client("https://supernova-mcp.knotapi.com/mcp", http_client=http_client) > > async with Client(transport) as client: > tools = await client.list_tools() > result = await client.call_tool("supernova_list_accounts", {}) > print(result.structured_content) > ``` ## 4. Interact with Supernova in your agent Ask your agent to do something on a site, such as "Find me some tasty ice cream." If the action requires authentication to an online account and an account is not linked, your agent gets a sign-in link from the Supernova MCP and will return it to you to sign-in. ## Linking online accounts Some actions need the user's own account at a site. The agent calls `supernova_list_accounts` and `supernova_link_account` to check whether the user has a linked account there. If not, it gets a sign-in link and returns it to the user in the UI, the user confirms a code texted to their phone, and signs in to the site. The agent never asks for the user's username or password to the site. OTP codes are texted to the phone number provided in [Create MCP Token](https://docs.knotapi.com/api-reference/mcp-tokens/create-mcp-token.md). ## Running actions The agent sends the user's request to `supernova_do` in plain language. Supernova routes it to the right action, runs it, and returns only the fields the request needs. Some sites also support guest actions, such as searching without signing in. The agent creates a guest session with `supernova_create_guest_session` and passes its ID as `session`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.