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

Any package.json-based TypeScript project qualifies, whichever package manager you use — npm, pnpm, Yarn, or Bun. The one setup Carrick can’t scan yet is a Deno-native project with no package.json; see What Carrick covers for details.

There is no API key to create or store anywhere in this flow. Scan uploads authenticate through the GitHub App and GitHub Actions OIDC, and your agent authenticates through a browser sign-in.

1. Sign in with GitHub

Go to app.carrick.tools and click Sign in with GitHub. Carrick requests three OAuth scopes:

• read:user: your GitHub login and email.
• read:org: the orgs you belong to.
• public_repo: access to your public repos. GitHub’s OAuth scopes are coarse here — public_repo technically includes write access to public repos, because GitHub does not offer a narrower read-only OAuth scope. Carrick only ever reads.

Carrick stores your access token encrypted and uses it only to read what the scanner needs. Signing in lands you in your workspace’s dashboard, which walks you through the remaining steps as a checklist.

2. Install the GitHub App

From the dashboard, click Install to add the Carrick GitHub App and nominate the repos you want analyzed. The App is what authorizes scan uploads from those repos’ CI runs and posts the PR comments — no tokens or secrets involved.

Repos you nominate drop into your workspace’s default project. You can re-bucket them later from the Repos page.

3. Connect repos to a project

A project is one interconnected system: the group of repos that talk to each other. Carrick compares contracts within a project, so group the repos whose APIs call one another into the same project on the Repos page.

If everything you nominated belongs to one system, the default project is already correct and there is nothing to do.

4. Add the workflow

Each repo needs a GitHub Actions workflow so it gets scanned on every push and pull request. Two ways to add it:

Let your agent do it. Connect your agent over MCP (step 5 below), then paste the setup prompt from the dashboard. The agent calls Carrick’s scaffold tool and writes the workflow, a carrick.json it populates by reading your code, and an agent instruction block.

Or add it by hand. Save the following to .github/workflows/carrick.yml:

name: Carrick

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  # Reserved for Carrick Cloud dispatches (currently dormant). Cross-repo
  # results stay current without it: every scan reads the live index, and
  # Carrick re-runs affected open PRs when a sibling repo changes.
  repository_dispatch:
    types: [carrick-sibling-updated]

permissions:
  # Mint a short-lived OIDC token Carrick exchanges for keyless upload auth
  # (no upload secret to configure).
  id-token: write
  contents: read

jobs:
  carrick:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: carrick-tools/carrick@v1

A few things worth knowing about this file:

• Replace main if your default branch differs. The two branches: filters must name the repo’s actual default branch (master, develop, …) or the repo will never scan.
• id-token: write is required. It lets the job mint the short-lived OIDC token that Carrick exchanges for upload auth. Without it, the run fails with an explicit error telling you to add it.
• There is nothing in it about PR comments. Comments are posted by the GitHub App, not by the workflow, so the workflow needs no pull-requests permission and no comment step. See PR comments.
• The repository_dispatch trigger does nothing today. It is reserved so Carrick Cloud can dispatch to repos in the future without asking you to edit the workflow. Cross-repo results don’t depend on it: every scan reads the live index, and Carrick automatically re-runs affected open PRs when a sibling repo’s contracts change.

Pull requests from forks are skipped, not failed: GitHub withholds OIDC credentials from fork pull_request runs, so Carrick prints a notice and exits cleanly rather than turning an external contributor’s PR red.

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. The agent scaffold path writes this for you.

5. Connect your agent over MCP

One install serves every project in your workspace. Pick the snippet for your agent. The first request opens a browser tab on app.carrick.tools; sign in and click Approve to grant the agent read-only access to the index. Subsequent calls use the token the agent received.

Claude Code

claude mcp add --scope user --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"]

See Connecting your agent for the manual-token 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 project’s index (main-branch runs only; pull-request runs analyze without uploading).

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 project 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. How the App’s contract-drift comments work and how to toggle them per project.
• carrick.json. Classify env-var-driven outbound calls so contract checking can run against them.