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](https://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`:

```yaml
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](/pr-output).

If your repo uses environment variables to build outbound URLs (`fetch(`${process.env.USER_SERVICE_URL}/users`)`), also add a [carrick.json](/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

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

### Cursor

Save to `~/.cursor/mcp.json`:

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

### Windsurf

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

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

### Codex

Save to `~/.codex/config.toml`:

```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](/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](/mcp-tools) for the full set.

## What to set up next

- [Connecting your agent](/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](/pr-output). Extend the workflow to post the action's `pr-comment` output on pull requests, updating in place across pushes.
- [carrick.json](/carrick-json). Classify env-var-driven outbound calls so contract checking can run against them.