Connecting your agent

Coding agents interact with Carrick through three distinct channels:

1. Hosted MCP server: Answers queries on demand at https://api.carrick.tools/mcp across your entire organisation (including repositories that are not checked out locally), providing semantic intent search, cross-service call graphs, caller lookups, and compiler-resolved endpoint types.
2. Local hooks: Deliver instant feedback in Claude Code and Codex directly in the same turn as a file edit without invoking remote models, reporting routes, calls, local counterparts, and broken contracts.
3. Editor diagnostics: Surface contract drift and type mismatch errors in the IDE Problems panel for editor-integrated agents.

MCP client configuration

The Carrick MCP server runs over HTTP transport at https://api.carrick.tools/mcp. Configure your agent client using the appropriate method below.

Claude Code

Discovery (recommended):

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

On the first tool call, Claude Code opens the browser OAuth consent flow. Approving the request stores a workspace-level credential that persists across sessions. The --scope user flag makes the server available across all local projects.

Manual key fallback:

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

Cursor

Discovery:

Add the following to ~/.cursor/mcp.json:

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

Restart Cursor. The first tool invocation opens the browser authorization screen.

Manual key fallback:

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

Windsurf

Discovery:

Add the following to ~/.codeium/windsurf/mcp_config.json:

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

Manual key fallback:

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

VS Code

Discovery:

Save the configuration in your user mcp.json file:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Linux: ~/.config/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json

{
  "servers": {
    "carrick": {
      "type": "http",
      "url": "https://api.carrick.tools/mcp"
    }
  }
}

For manual keys, add an Authorization: Bearer <YOUR_MCP_KEY> header as supported by your VS Code configuration.

Codex

Discovery:

codex mcp add carrick --url https://api.carrick.tools/mcp
codex mcp login carrick

Manual key fallback:

export CARRICK_MCP_TOKEN='<YOUR_MCP_KEY>'
codex mcp add carrick --url https://api.carrick.tools/mcp \
  --bearer-token-env-var CARRICK_MCP_TOKEN

Other MCP clients

For clients supporting HTTP transport MCP servers, target https://api.carrick.tools/mcp directly with an Authorization: Bearer <YOUR_MCP_KEY> header. For clients that require stdio transport, run a standard HTTP-to-stdio MCP bridge.

Agent usage rules

To ensure your agent consults Carrick before grepping repositories or re-implementing existing functions, add the following section to your repository’s AGENTS.md or CLAUDE.md:

## Carrick

Carrick indexes every TypeScript service in this org. Read the file you are editing. For anything that lives elsewhere (a helper, an endpoint, a consumer, a type), ask Carrick first, then grep to confirm a location:

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

Local channels and coordination

Carrick coordinates local feedback mechanisms so you receive consistent diagnostics without duplicate output:

• Claude Code hooks: carrick init registers a PostToolUse hook (executing carrick hook post-edit on file edits) and a SessionStart hook (carrick hook session-start). The post-edit hook inspects local index data and returns diagnostics in the same turn as the edit.
• Language server: To run the LSP server directly in Claude Code, load the bundled plugin:

  claude --plugin-dir "$(npm root -g)/carrick/plugin"

  When the post-edit hook is active, the language server suppresses duplicate terminal messages.
• Environment override: Set CARRICK_CHANNEL=off to disable all local hook and language server reporting.

Terminal agents without MCP support can execute carrick check <file> --json to inspect contract verdicts directly.

Authentication and token management

Carrick authenticates CLI tools and MCP clients independently:

• CLI Authentication: carrick login authenticates the local CLI to download and synchronise index data.
• MCP Client Authentication: Agent clients authenticate via OAuth browser consent or manual bearer tokens to query hosted tools.

Both authentication methods grant read-only access scoped to your Carrick workspace. Agents cannot modify index records, trigger scans, or alter organisation settings.

Manage active API keys and tokens on the Account page. Revoking a token disables access within one minute.

Related

• Task skills covers the four specialised workflows installed for coding agents.
• In your editor covers IDE extensions and Problems panel integration.
• Quickstart provides the end-to-end onboarding walkthrough.
• MCP tools contains the complete reference for hosted tools and schemas.