# 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.

```text title="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](https://www.subbly.co/admin/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:

```bash title="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.

```bash title="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.

```json title=".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

<a href="cursor://anysphere.cursor-deeplink/mcp/install?name=subbly&config=eyJ1cmwiOiJodHRwczovL21jcC5zdWJibHkuZGV2L21jcCIsImhlYWRlcnMiOnsiWC1BUEktS0VZIjoiUFJJVkFURS1BUEktS0VZIn19">Add to Cursor</a>
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}`.

```json title=".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

<a href="vscode:mcp/install?%7B%22name%22%3A%22subbly%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.subbly.dev%2Fmcp%22%2C%22headers%22%3A%7B%22X-API-KEY%22%3A%22PRIVATE-API-KEY%22%7D%7D">Install in VS Code</a>
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.

```json title=".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:

```json title="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.

```bash title="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](/developer-resources/subbly-mcp/tools) — everything the agent can
  now do.
- [Private API reference](/api/private) — the meaning of every field a tool
  takes.