The Carrick MCP server exposes your indexed services as structured tools and resources. The endpoint is `https://api.carrick.tools/mcp`, or `https://api.carrick.tools/mcp/p/<project-slug>` for a specific project. Your token is scoped to one project, and every tool returns data for that project only.

Tools are listed below in the order they typically fire during a coding session.

## Intent layer

### `search_by_intent(query, top_k?, similarity_threshold?)`

Semantic search across every exported function in the org, ranked by how closely each matches your query.

Reach for it when the agent is asking a concept question ("verify a webhook signature", "dedupe users by email") where keywords do not help. It searches the whole org, not a sampled subset.

**Parameters:**

| Name | Type | Required | Default | Notes |
| :--- | :--- | :--- | :--- | :--- |
| `query` | string | yes | | Plain-English description of what the function should do. |
| `top_k` | number | no | 8 | How many matches to return. |
| `similarity_threshold` | number | no | 0.3 | Score floor for inclusion. Raise to filter weak matches; lower to widen results. |

**Response shape:**

```json
{
  "query": "verify a webhook signature",
  "top_k": 8,
  "similarity_threshold": 0.3,
  "total_embedded_scanned": 1247,
  "total_above_threshold": 4,
  "results": [
    {
      "service": "billing",
      "repo": "billing-service",
      "name": "verifyStripeWebhook",
      "file_path": "src/webhooks/stripe.ts",
      "line_number": 24,
      "intent": "Verifies a Stripe webhook signature using the signing secret and rejects requests with mismatched HMACs.",
      "similarity": 0.82
    }
  ]
}
```

### `list_function_intents(service?, exclude_service?)`

Returns the full haystack of every exported function in the org alongside its LLM-generated intent. Useful for browsing a service's surface area, or for comparing what sibling services have implemented.

Prefer `search_by_intent` for concept queries. Use this when you want to scan a whole service end to end, or to diff implementations across two services.

**Parameters:**

| Name | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `service` | string | no | Restrict to one service. |
| `exclude_service` | string | no | Restrict to everything except one service. |

**Response shape:**

```json
{
  "total": 1247,
  "services": ["billing", "checkout", "inventory"],
  "functions": [
    {
      "service": "billing",
      "repo": "billing-service",
      "name": "verifyStripeWebhook",
      "file_path": "src/webhooks/stripe.ts",
      "line_number": 24,
      "intent": "Verifies a Stripe webhook signature using the signing secret and rejects requests with mismatched HMACs."
    }
  ]
}
```

## Structural and type layer

### `list_services()`

Catalogue of every service in the org's index. Cheap. Call this first when orienting.

**Response shape:**

```json
[
  {
    "repo_name": "billing-service",
    "service_name": "billing",
    "endpoint_count": 14,
    "call_count": 9,
    "last_updated": "2026-05-24T19:02:11Z",
    "commit_hash": "a3f1c9d",
    "has_types": true
  }
]
```

### `get_api_endpoints(service, method?, path_contains?)`

Endpoints a service exposes. Returns one row per endpoint with HTTP method, fully-resolved path (mount-aware), handler reference, mount owner, and the source file location.

Reach for it before writing client code that calls a service, or before changing one of its routes.

**Parameters:**

| Name | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `service` | string | yes | The service to inspect. |
| `method` | string | no | Filter to one HTTP method (`GET`, `POST`, ...). |
| `path_contains` | string | no | Substring filter on path. |

**Response shape:**

```json
{
  "service": "billing",
  "endpoint_count": 1,
  "endpoints": [
    {
      "method": "POST",
      "full_path": "/api/v1/invoices",
      "handler": "createInvoice",
      "owner": "billingRouter",
      "file_location": "src/routes/invoices.ts:42"
    }
  ]
}
```

### `get_endpoint_types(service, method, path)`

Resolved TypeScript request and response types for a single endpoint. Each entry tells you whether the type was explicitly annotated or inferred from the handler body, and includes the source location.

Reach for it before building a request body or parsing a response. Guessing JSON shapes from a sample is the most common source of contract drift.

**Parameters:**

| Name | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `service` | string | yes | The service exposing the endpoint. |
| `method` | string | yes | HTTP method. |
| `path` | string | yes | Path, matched against the service's mount graph. |

**Response shape:**

```json
{
  "service": "billing",
  "method": "POST",
  "path": "/api/v1/invoices",
  "types": [
    {
      "type_alias": "CreateInvoiceRequest",
      "type_kind": "request_body",
      "is_explicit": true,
      "source_file": "src/types/invoices.ts",
      "source_line": 12,
      "definition": "{ customer_id: string; amount_cents: number; currency: string }"
    },
    {
      "type_alias": "Invoice",
      "type_kind": "response_body",
      "is_explicit": false,
      "source_file": "src/routes/invoices.ts",
      "source_line": 58,
      "definition": "{ id: string; status: 'open' | 'paid'; amount_cents: number }"
    }
  ]
}
```

### `get_type_definition(service, type_alias)`

Fully resolved definition for one named type, with transitive dependencies expanded. Use it when `get_endpoint_types` references a named DTO, discriminated union, or composed type whose shape you need to read.

**Parameters:**

| Name | Type | Required |
| :--- | :--- | :--- |
| `service` | string | yes |
| `type_alias` | string | yes |

**Response shape:**

```json
{
  "service": "billing",
  "type_alias": "Invoice",
  "definition": "{ id: string; status: InvoiceStatus; amount_cents: number; line_items: LineItem[] }",
  "expanded": "{ id: string; status: 'open' | 'paid' | 'void'; amount_cents: number; line_items: { sku: string; quantity: number; unit_price_cents: number }[] }"
}
```

### `check_compatibility(consumer_service, producer_service, method?, path?)`

Diff a consumer's outbound calls against a producer's exposed endpoints. Surfaces missing endpoints (the consumer calls something the producer no longer exposes) and unused endpoints (the producer exposes routes that nobody calls).

Reach for it before removing a route, renaming a path, or changing a producer's response shape.

**Parameters:**

| Name | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `consumer_service` | string | yes | The service making the calls. |
| `producer_service` | string | yes | The service exposing the endpoints. |
| `method` | string | no | Limit to one HTTP method. |
| `path` | string | no | Limit to calls matching a path. |

**Response shape:**

```json
{
  "consumer": "checkout",
  "producer": "billing",
  "compatible": false,
  "consumer_calls": 6,
  "producer_endpoints": 14,
  "issues": [
    {
      "severity": "error",
      "category": "missing_endpoint",
      "message": "Consumer calls POST /api/v1/invoices/draft but producer has no matching endpoint"
    },
    {
      "severity": "info",
      "category": "unused_endpoint",
      "message": "Producer exposes DELETE /api/v1/invoices/:id but consumer doesn't call it"
    }
  ]
}
```

### `get_service_dependencies(service?)`

With no argument, returns org-wide npm dependency conflicts: any package pinned to more than one version across services. With a service name, returns that service's merged dependency map.

Reach for it before adding or upgrading an npm dependency, or when a TypeScript build error looks like a version mismatch.

**Parameters:**

| Name | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `service` | string | no | Omit for org-wide conflict view. |

**Org-wide response shape:**

```json
{
  "total_packages": 312,
  "conflict_count": 4,
  "conflicts": [
    {
      "package_name": "zod",
      "severity": "error",
      "versions": [
        { "service": "billing", "version": "3.22.4" },
        { "service": "checkout", "version": "4.0.1" }
      ]
    }
  ]
}
```

**Per-service response shape:**

```json
{
  "service": "billing",
  "package_count": 87,
  "dependencies": {
    "zod": { "version": "3.22.4" }
  }
}
```

## Onboarding

### `scaffold()`

Generates the files needed to onboard the current repo onto Carrick: the GitHub Actions workflow (`.github/workflows/carrick.yml`, keyless via OIDC), a `carrick.md` instruction block, and a `carrick.json` config skeleton. It returns the files plus instructions telling the agent to write each one and to fill in `carrick.json` by scanning the repo for its service name and the env vars and domains it calls.

Your coding agent calls this once per repo during setup. Takes no parameters.

## Resources

Resources are read-only URIs that the MCP client can fetch directly.

### `carrick://services`

Full service catalogue as JSON. Equivalent to `list_services()` but exposed as a resource so the client can subscribe to it.

### `carrick://services/{name}/types.d.ts`

Bundled `.d.ts` file for one service. Useful when you want the agent to read the whole type surface area in one fetch instead of round-tripping `get_type_definition` for each name.

## Errors and empty results

Every tool returns a single `text` content block containing JSON. Errors and empty results are represented as plain text inside the same block:

- Missing service: `Service "checkout" not found. Use list_services to see available services.`
- Empty search: `Scanned 1247 embedded intents but none scored above the similarity threshold of 0.3. Try a more concrete phrase, or relax similarity_threshold.`
- Missing types: `Endpoint POST /api/v1/invoices exists but has no extracted types.`

Treat any response whose first character is not `{` or `[` as a textual diagnostic rather than a structured payload.

## Related

- [Connecting your agent](/connecting-your-agent) covers the setup that gates access to these tools, and the instruction block that tells your agent when to reach for each.
- [Quickstart](/quickstart) walks the full setup end to end.