MCP tools

Reference for every tool and resource the Carrick MCP server exposes at api.carrick.tools/mcp.

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:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

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 walks the full setup end to end.

MCP tools

Intent layer

search_by_intent(query, top_k?, similarity_threshold?)

list_function_intents(service?, exclude_service?)

Structural and type layer

list_services()

get_api_endpoints(service, method?, path_contains?)

get_endpoint_types(service, method, path)

get_type_definition(service, type_alias)

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

get_service_dependencies(service?)

Onboarding

scaffold()

Resources

carrick://services

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

Errors and empty results

Related

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

`list_function_intents(service?, exclude_service?)`

`list_services()`

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

`get_endpoint_types(service, method, path)`

`get_type_definition(service, type_alias)`

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

`get_service_dependencies(service?)`

`scaffold()`

`carrick://services`

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