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.

The token the agent receives is scoped to your whole workspace: one install serves every project in it, and each tool call resolves to a single project from the project/repo arguments the agent passes (see Project scoping).

If your client can’t sign in through the browser, mint an MCP key instead: open the workspace page in the dashboard and use Or create an MCP key manually. MCP keys are workspace-scoped, same as the browser-flow tokens. Paste the key into your client’s config as a bearer token — the “Manual fallback” sections below show how for each client.

Claude Code

Discovery (recommended)

claude mcp add --scope user --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. --scope user registers the server once for your whole machine; since one Carrick connection already serves every project in the workspace, there is no reason to reinstall it per project.

Manual fallback

claude mcp add --scope user --transport http carrick https://api.carrick.tools/mcp \
  --header "Authorization: Bearer <YOUR_MCP_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_MCP_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_MCP_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_MCP_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_MCP_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.

Managing tokens

Tokens exist only on the agent side. CI scans authenticate through the GitHub App and GitHub Actions OIDC, so there is no key to configure, store, or rotate on your repos.

The Account page at app.carrick.tools lists your active keys — prefix, workspace, and kind — with a Revoke button per key. Tokens minted by the browser sign-in flow and manually created MCP keys both appear here; a revoked key stops working within a minute. Deleting your account revokes all of them.

Related

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