Quickstart

This guide takes you from zero to a working Carrick install: an indexed repo, an agent talking to the MCP server, and the first PR comment posted automatically.

You will need a GitHub account, repo admin access to whichever TypeScript repos you want indexed, and an MCP-aware agent (Claude Code, Cursor, Windsurf, or Codex).

1. Sign in with GitHub

Go to app.carrick.tools and click Sign in with GitHub. Carrick requests read-only scopes:

• read:user: your GitHub login and email.
• read:org: the orgs you belong to, so you can scope your account to one of them on the next screen.
• public_repo: read access to your public repos.

Carrick stores your access token securely and uses it only to read what the scanner needs.

2. Pick your scope

If your GitHub account belongs to one or more orgs, the next screen asks you to pick where this Carrick account’s keys live: your personal namespace, or one of the orgs you belong to. Teammates who pick the same org share scan data and cross-repo discovery; teammates who pick different orgs see different indexes.

The scope is locked in for this account. To use Carrick with a different scope later, delete the account and sign in again.

Solo accounts (no org memberships) skip this step entirely and land on the dashboard with a personal-namespace key ready.

3. Copy your API key

The dashboard shows the plaintext API key once, on first login. Copy it now and add it as a repository secret named CARRICK_API_KEY on every repo you want scanned:

1. In GitHub, open the repo’s Settings → Secrets and variables → Actions.
2. Click New repository secret.
3. Name: CARRICK_API_KEY. Value: paste the key you copied from the dashboard.

If you lose the key, return to the dashboard and use Rotate key. The current key stops working immediately, so update CARRICK_API_KEY on every repo before the next scan runs.

4. Add the GitHub Action workflow

In each TypeScript repo you want indexed, save the following to .github/workflows/carrick.yml:

name: Carrick

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  carrick:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: daveymoores/carrick@v1
        with:
          carrick-api-key: ${{ secrets.CARRICK_API_KEY }}

This is the default workflow the dashboard generates. It scans on every push to main and on every pull request. On main, the action uploads results to the index. On pull requests, the action runs the analysis and exposes a pr-comment output without posting it. To turn that output into a PR comment, see PR comments.

If your repo uses environment variables to build outbound URLs (fetch(${process.env.USER_SERVICE_URL}/users)), also add a carrick.json at the repo root to tell the scanner which env vars name internal services and which name third-party APIs.

5. Connect your agent over MCP

Pick the snippet for your agent. The first request opens a browser tab on app.carrick.tools/oauth/authorize; click Approve to grant the agent read-only access to the index. Subsequent calls use the long-lived token the agent received.

Claude Code

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

Cursor

Save to ~/.cursor/mcp.json:

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

Windsurf

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

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

Codex

Save to ~/.codex/config.toml:

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

For agents that do not support MCP OAuth discovery, you can paste the API key into the connection headers directly. See Connecting your agent for the manual variants and the consent-screen details.

6. Your first scan

Push to main (or open a pull request) on any repo that now has .github/workflows/carrick.yml. The action will:

1. Download the Carrick release.
2. Scan the repo’s TypeScript source.
3. Upload the results to your org’s index (main-branch runs only; pull-request runs skip the upload).

After the action finishes, your agent can immediately call MCP tools. Ask it something only Carrick should know:

Use Carrick to list every service in our org and the number of endpoints each one exposes.

The agent calls list_services and answers in one turn. See MCP tools for the full set.

What to set up next

• Connecting your agent. Add a short Carrick block to your AGENTS.md so your agent knows when to reach for Carrick before grepping or reimplementing.
• PR comments. Extend the workflow to post the action’s pr-comment output on pull requests, updating in place across pushes.
• carrick.json. Classify env-var-driven outbound calls so contract checking can run against them.