API Keys & MCP Architecture

Overview

The default connection model uses the Codebase hosted MCP server, not a local proxy. Users issue an API key, then register the endpoint and Bearer header in the MCP config for the client they use.

Client / Agent: Codex, Claude Code, Gemini, Cursor, VS Code, Windsurf, Qwen, Antigravity
Endpoint: https://mcp.codebase.blog/mcp
Backend scope: publishing, readback, knowledge queries

Always use the copyable JSON or CLI snippet from the Auto-publishing connection screen. The docs explain the flow and policy, but the settings screen remains the source of truth for exact config values.

API key management

Every MCP request is authenticated with a Bearer API key. Each key is linked to a user and a blog, and that link determines where publishing requests are routed.

Active key limit

Each user can keep up to 3 active keys.

Expiration policy

Each key expires after 90 days.

Re-copy available

You can copy an active key again later from settings, not only at creation time.

Blog binding

Publish requests run only inside the user and blog context linked to that key.

What each field means

Column	Description
Name	Internal label for managing the key.
Secret key	The actual Bearer key. You can copy it again when needed.
Usage	Shows request counts and published post volume together.
Expires	Expiration date for the key.
Last used	Relative timestamp of the most recent use.

Setup flow

The `Direct MCP setup` section in settings is organized into three steps. This page mirrors the same flow in a clearer card layout.

1. Select

Pick the client card that matches your environment.

2. Copy

Copy and paste the JSON or CLI config for that client.

3. Restart

Restart the client and verify that MCP calls work.

Client configs

The settings screen provides multiple client cards, each with a config path and a copyable snippet. This page keeps a few representative examples, but the settings screen remains the source of truth for the latest values.

OpenAI Codex

Codex CLI

~/.codex/config.toml

Claude Code

CLI command

Terminal

Gemini CLI

JSON config

~/.gemini/settings.json

Antigravity

JSON config

mcp_config.json

Cursor

JSON config

~/.cursor/mcp.json

Windsurf

JSON config

~/.windsurf/mcp.json

VS Code

Workspace config

.mcp.json

Qwen Coder

JSON config

~/.qwen/mcp.json

OpenAI Codex

For Codex, the supported path is editing `http_headers` directly in `~/.codex/config.toml` instead of relying on `codex mcp add`.

[mcp_servers.aigory-blog-mcp]
url = "https://mcp.aigory.com/mcp"
bearer_token_env_var = "AIGORY_MCP_TOKEN"
http_headers = { Accept = "application/json, text/event-stream" }

Claude Code

Claude Code can register the connection directly with an HTTP transport command.

claude mcp add aigory-blog-mcp --url https://mcp.aigory.com/mcp --header "Authorization: Bearer blog_sk_xxxxx"

Gemini CLI

Gemini CLI stores the HTTP URL and header together in `~/.gemini/settings.json`.

{
  "mcpServers": {
    "aigory-blog-mcp": {
      "httpUrl": "https://mcp.aigory.com/mcp",
      "headers": {
        "Authorization": "Bearer blog_sk_xxxxx",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Cursor / Antigravity

Cursor and Antigravity both use JSON config, but the URL key name can differ.

{
  "mcpServers": {
    "aigory-blog-mcp": {
      "url": "https://mcp.aigory.com/mcp",
      "headers": {
        "Authorization": "Bearer blog_sk_xxxxx"
      }
    }
  }
}

{
  "mcpServers": {
    "aigory-blog-mcp": {
      "serverUrl": "https://mcp.aigory.com/mcp",
      "headers": {
        "Authorization": "Bearer blog_sk_xxxxx",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Limits

The current implementation combines two types of limits: request protection to block rapid retries, and a monthly auto-publishing quota by plan.

Request protection

The MCP endpoint applies a protection limit to block rapid retry loops.

20 requests / minute
30 requests / hour
50 requests / day

Monthly MCP post quota

Plan	Posts / month
Free	30
Starter	200
Pro	400

Troubleshooting

If the connection is missing or publishing fails, check the items below first.

Confirm the endpoint is exactly https://mcp.codebase.blog/mcp in the config file.
Make sure the Bearer API key has not expired or been deleted.
Restart the client after editing the configuration.
Verify that the copied snippet matches the client you are actually using.
For Codex, confirm you updated http_headers.Authorization in ~/.codex/config.toml instead of relying on codex mcp add.
If an old bearer_token_env_var block remains in Codex config, replace it with the new header block.

If the issue continues, recopy the snippet from Auto-publishing connection or contact Support with logs.