Copy page

Subbly MCP server

Connect a client

The server runs at one URL and speaks the streamable HTTP transport, so any MCP client that supports HTTP servers with a custom header can use it.

MCP server URL
https://mcp.subbly.dev/mcp

Every request must carry your Private API key in the X-API-KEY header. The server does not store the key; it creates a fresh Private API client for each tool call with the key that came in.

Get your API key

Private API keys live in the Subbly admin under Settings › API keys. In the Private API keys card, click Generate API key to create one for the agent, then copy it with the icon next to it. You can keep several keys, so give the agent its own; if it leaks, delete that key from the same card and generate a new one. A key can read and change everything in your shop, so treat it as a password and keep it out of files you commit.

Each client below can read the key from an environment variable. Export it once in your shell:

Export the key
export SUBBLY_PRIVATE_API_KEY='PRIVATE-API-KEY'

Claude Code

One command adds the server. Use --scope user to make it available in every project, or leave the default to keep it to the current one.

Add the server
claude mcp add --transport http subbly https://mcp.subbly.dev/mcp \
  --header "X-API-KEY: ${SUBBLY_PRIVATE_API_KEY}"

To share the setup with a team without sharing the key, commit a .mcp.json in the project root instead. Claude Code expands ${VAR} from the environment when it reads the file.

.mcp.json
{
  "mcpServers": {
    "subbly": {
      "type": "http",
      "url": "https://mcp.subbly.dev/mcp",
      "headers": {
        "X-API-KEY": "${SUBBLY_PRIVATE_API_KEY}"
      }
    }
  }
}

Run claude mcp list to check that the server shows as connected, then ask Claude something like "list my published subscription products".

Cursor

Add to Cursor opens Cursor with the server filled in; replace PRIVATE-API-KEY with your key before you save.

Or add it by hand to .cursor/mcp.json in the project, or to ~/.cursor/mcp.json for every project. Cursor reads environment variables with ${env:VAR}.

.cursor/mcp.json
{
  "mcpServers": {
    "subbly": {
      "url": "https://mcp.subbly.dev/mcp",
      "headers": {
        "X-API-KEY": "${env:SUBBLY_PRIVATE_API_KEY}"
      }
    }
  }
}

The server appears under Settings › MCP with its tools listed. Toggle it on if it is off.

VS Code

Install in VS Code opens VS Code with the server filled in; replace PRIVATE-API-KEY with your key before you save.

Or add it by hand to .vscode/mcp.json, or run MCP: Open User Configuration to add it for every workspace. An inputs entry asks for the key once and stores it in the secret store, so it never lands in the file.

.vscode/mcp.json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "subbly-api-key",
      "description": "Subbly Private API key",
      "password": true
    }
  ],
  "servers": {
    "subbly": {
      "type": "http",
      "url": "https://mcp.subbly.dev/mcp",
      "headers": {
        "X-API-KEY": "${input:subbly-api-key}"
      }
    }
  }
}

Any other client

Most clients take the same JSON shape. Give it the URL and the header:

Generic config
{
  "mcpServers": {
    "subbly": {
      "url": "https://mcp.subbly.dev/mcp",
      "headers": {
        "X-API-KEY": "PRIVATE-API-KEY"
      }
    }
  }
}

Try it in the MCP Inspector

The Inspector is a browser UI for calling tools by hand. It is the quickest way to see what a tool returns before you hand it to an agent.

Open the Inspector
npx @modelcontextprotocol/inspector

In the Inspector pick Streamable HTTP, enter the server URL, add an X-API-KEY header under Authentication and click Connect. The Tools tab lists every tool with its input schema.

What the client sees

• Tools only. The server offers tools, no prompts or resources.
• Structured output. Every tool returns its result twice: as JSON text in content and as structuredContent, typed by the tool's output schema.
• Stateless. Each request is its own session. Nothing is remembered between calls, so a client can reconnect at any time.
• Errors. A tool that fails returns an MCP error whose message starts with Tool execution failed: followed by the Private API's message. A missing key returns API key is required.

Clients that need OAuth

Claude.ai, Claude Desktop and ChatGPT add remote servers as connectors, and a connector cannot send a custom header. Those clients need an OAuth flow, which the server does not offer today. Use one of the clients above.

Next steps

• Tools — everything the agent can now do.
• Private API reference — the meaning of every field a tool takes.