Connecting your agent

Carrick’s MCP endpoint runs at https://api.carrick.tools/mcp over HTTP transport. Any MCP-aware agent that supports HTTP servers can connect. This guide covers the four clients with first-class snippets in the dashboard.

How the connection works

The recommended setup signs you in through your browser. The first time your agent calls Carrick, it opens a consent screen. Sign in, click Approve, and your agent stays connected across sessions.

The consent screen lists what the agent can read once approved:

• Function intents
• Type definitions
• Dependencies and version drift
• API endpoints with request and response types
• Cross-service contract compatibility

All of this is read-only. The agent can’t write to the index, change settings, or trigger scans.

If your client can’t sign in through the browser, paste an API key from the dashboard into its config instead. The “Manual fallback” sections below show how for each client.

Claude Code

Discovery (recommended)

claude mcp add --transport http carrick https://api.carrick.tools/mcp

Claude opens the consent URL on the first tool call. Approve once, and the token persists across sessions.

Manual fallback

claude mcp add --transport http carrick https://api.carrick.tools/mcp \
  --header "Authorization: Bearer <YOUR_CARRICK_API_KEY>"

Use this only if discovery is unavailable, or for a service account.

Cursor

Discovery

Save to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "carrick": {
      "url": "https://api.carrick.tools/mcp"
    }
  }
}

Restart Cursor. The first tool call opens the consent screen in your browser.

Manual fallback

{
  "mcpServers": {
    "carrick": {
      "url": "https://api.carrick.tools/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_CARRICK_API_KEY>"
      }
    }
  }
}

Windsurf

Discovery

Save to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "carrick": {
      "serverUrl": "https://api.carrick.tools/mcp"
    }
  }
}

Manual fallback

{
  "mcpServers": {
    "carrick": {
      "serverUrl": "https://api.carrick.tools/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_CARRICK_API_KEY>"
      }
    }
  }
}

Codex

Codex talks to MCP servers through mcp-remote, which terminates HTTP transport locally.

Discovery

Save to ~/.codex/config.toml:

[mcp_servers.carrick]
command = "npx"
args = ["-y", "mcp-remote", "https://api.carrick.tools/mcp"]

Manual fallback

[mcp_servers.carrick]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://api.carrick.tools/mcp",
  "--header",
  "Authorization: Bearer <YOUR_CARRICK_API_KEY>",
]

Tell your agent when to use Carrick

Connecting the server makes the tools available, but your agent won’t reach for them unless it knows to. Carrick’s MCP server ships a default set of usage rules, and clients that read them (Claude Code, Cursor) pick them up automatically, so often you don’t need to do anything.

To make the rules explicit, or add your own, paste this into your repo’s AGENTS.md (or CLAUDE.md / .cursor/rules/, whichever your agent reads):

## Carrick

Carrick indexes every TypeScript service in this org. When working in TypeScript, use it before grepping or reimplementing:

- Before writing a helper, parser, validator, or formatter: `search_by_intent` to find an existing one ("dedupe users by email", "verify a webhook signature").
- Before calling another service: `get_api_endpoints`, then `get_endpoint_types` instead of guessing the JSON.
- Before changing a route, a response shape, or an HTTP verb: `check_compatibility` against each consumer.
- Before adding or bumping an npm dependency: `get_service_dependencies`.

Carrick is read-only; data reflects each repo's last scan.

Other MCP clients

If your client supports HTTP-transport MCP servers, point it at https://api.carrick.tools/mcp. If the client does not support OAuth discovery, add an Authorization: Bearer <YOUR_CARRICK_API_KEY> header to the request.

If your client only supports stdio transport, run mcp-remote as a shim, the same way the Codex config above does.

Rotating the API key

If you need to revoke a token (lost laptop, suspected leak, scheduled rotation), open the dashboard at app.carrick.tools and click Rotate key. The previous key stops working immediately. Update every place the key is configured:

• CARRICK_API_KEY in GitHub Actions secrets on every indexed repo.
• The Authorization header on any agent using the manual fallback.

Tokens from the browser sign-in flow keep working after a rotation. Rotating the API key only affects clients using the manual fallback.

Related

• Quickstart covers the end-to-end signup and first scan.
• MCP tools is the reference for what the agent can call.