MCP tools

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

The Carrick Model Context Protocol (MCP) server at https://api.carrick.tools/mcp provides AI coding agents with direct access to your compiled project index. Agents can query cross-service call graphs, inspect TypeScript request and response types, evaluate contract compatibility, and search for reusable functions across services.

Authentication tokens are scoped to your Carrick workspace, and individual tool calls resolve to a specific project within that workspace.

Every tool is read-only, and each one says so in tools/list with a display title and the MCP annotations readOnlyHint: true and destructiveHint: false.

Every JSON response includes a top-level server_build identifying the server build. Older servers named this field carrick_version. It versions the server, not the carrick CLI. Diagnostic tools such as check_compatibility and get_service_graph also include a matcher_version identifying the matching engine release.

Project scoping

A Carrick workspace can contain multiple projects, where each project represents an interconnected system of repositories. All data tools accept two optional parameters to target a specific project:

Name	Type	Notes
`project`	string	Carrick project slug to query.
`repo`	string	Your repo as `owner/repo` (from the git remote) or the repo name alone. Carrick resolves which project it belongs to.

Pass project or repo on each tool invocation. When a workspace contains only one project, you can omit both parameters.

Repositories onboarded using scaffold() record the project slug in .claude/skills/carrick/SKILL.md or in the ## Carrick section of AGENTS.md or CLAUDE.md.

If a query does not resolve to a single project, the tool returns an informational message listing available projects. You can call list_projects to view all valid slugs.

Semantic search and code reuse

`search_by_intent(query, also_phrased_as?, top_k?, similarity_threshold?, offset?, compact?)`

search_by_intent searches all indexed functions across a project by semantic behaviour, ranking results by cosine similarity against your query description.

Use this tool when looking for existing implementations of a concept across services (such as “verify a webhook signature” or “dedupe users by email”). It queries the full project index rather than a sampled subset.

Parameters:

Name	Type	Required	Default	Notes
`query`	string	yes		Plain-English description of what the function should do.
`also_phrased_as`	string[]	no		Up to 2 more wordings of the same concept, such as the mechanism as well as the purpose. One call runs all of them and returns one deduped list. For separate questions, call the tool once per question.
`top_k`	number	no	8	How many matches to return (max 50).
`similarity_threshold`	number	no	0.3	Lowest score a match needs to be included. Raise it to filter weak matches, or lower it to widen results.
`offset`	number	no	0	How many ranked matches to skip. Pass a previous response’s `next_offset` to page through.
`compact`	boolean	no	false	Return only a locator for each row: name, path, line span and similarity. Use it when you list many functions at once.

Response shape:

{
  "query": "verify a webhook signature",
  "phrasings": ["verify a webhook signature", "compare an HMAC header against a computed digest"],
  "top_k": 8,
  "similarity_threshold": 0.3,
  "total_embedded_scanned": 1247,
  "total_above_threshold": 4,
  "total_without_intent": 0,
  "total_without_intent_by_design": 0,
  "total_intent_not_embedded": 0,
  "hidden_by_threshold": {
    "count": 2,
    "best": {
      "name": "checkSignatureHeader",
      "file_path": "src/webhooks/verify.ts",
      "line_number": 61,
      "similarity": 0.27
    }
  },
  "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,
      "matched_phrasings": [0, 1]
    }
  ]
}

Multi-phrasing queries

When providing alternative wordings via also_phrased_as, the response includes phrasings listing all evaluated queries. Each result’s matched_phrasings array contains indices corresponding to the queries that retrieved that function.

Threshold filtering and unindexed functions

Results combine semantic vector similarity and lexical token matching. similarity_threshold filters rows retrieved solely by semantic similarity; lexical matches are preserved even if their similarity score is low.

The hidden_by_threshold object reports the number of semantic matches omitted below the threshold along with the highest-scoring excluded function. total_without_intent counts indexed functions with no intent text, and total_without_intent_by_design counts how many of those the scan was never going to describe: a single-line body, or a file’s top-level row. The difference between the two is the only part that a later scan fills in. total_without_intent_by_design is null when a service in the answer was indexed before the split was recorded.

`find_similar(functions?, service?, min_lines?, similarity_threshold?, include_tests?, include_generated?, include_callbacks?, top_k?, limit?, offset?)`

find_similar detects duplicate or near-duplicate functions across a project in two operational modes:

Targeted mode: Pass specific function names or descriptions in functions to find existing helpers that perform the same task.
Audit mode: Omit functions to perform a project-wide cluster analysis identifying functions implemented redundantly across services.

Comparisons evaluate generated intent descriptions rather than raw source code tokens.

Parameters:

Name	Type	Required	Default	Notes
`functions`	object[]	no		Up to 20 entries. Each is a `name` with a `file` for a function the index holds, or a `description` for one that is not indexed yet. Use one or the other in an entry, never both. Omit for the audit.
`service`	string	no		Limit the comparison to one service. Use it when an audit reports more functions than one pass compares.
`min_lines`	number	no	3 audit, 1 targeted	Shortest function to compare. One-line and two-line wrappers have no behaviour worth reusing. The response says how many rows this setting hid.
`similarity_threshold`	number	no	0.85 indexed, 0.45 description	Lowest score a match needs. The two defaults differ because an indexed function uses its stored vector, while a description is embedded when you call. The response’s `vector_basis` says which stored vectors it compared.
`include_tests`	boolean	no	false	Include test files, which repeat each other by design.
`include_generated`	boolean	no	false	Include generated and bundled files.
`include_callbacks`	boolean	no	false	Include the anonymous callbacks the scan indexed. You can’t import a callback, so a group of them is not a reuse finding.
`top_k`	number	no	5	Matches per entry in the targeted mode (max 20).
`limit`	number	no	20	Most groups per page in the audit mode (max 50). A page can come back shorter, because it’s cut to what one response holds. `clusters_note` says what the page holds, and `next_offset` continues it.
`offset`	number	no	0	Groups to skip in the audit mode. Pass a previous response’s `next_offset` to page through.

Targeted response shape:

{
  "mode": "targeted",
  "compared_functions": 2118,
  "excluded": { "below_min_lines": 0, "tests": 0, "generated": 0, "callbacks": 174, "other_service": 0 },
  "not_compared": { "without_intent": 42, "intent_not_embedded": 0, "awaiting_embedding": 0, "model_mismatch": 0, "intent_vector_missing": 0 },
  "results": [
    {
      "input": "slugify (src/text.ts:12)",
      "kind": "indexed",
      "similarity_threshold": 0.85,
      "matches": [
        {
          "repo": "checkout",
          "services": ["checkout"],
          "name": "toUrlSlug",
          "file_path": "src/util/url.ts",
          "line_number": 4,
          "end_line": 11,
          "exported": true,
          "signature": "(input: string) => string",
          "intent": "Lowercases a string and replaces every run of non-alphanumeric characters with a single hyphen.",
          "similarity": 0.93,
          "matched_on": "similarity"
        }
      ]
    }
  ]
}

matched_on indicates whether the match was identified by semantic vector proximity (similarity) or normalised intent string matching (intent_text).

Audit response shape:

{
  "mode": "audit",
  "min_lines": 3,
  "compared_functions": 2118,
  "total_clusters": 9,
  "near_exact_similarity": 0.95,
  "expanded_members": 5,
  "offset": 0,
  "clusters_returned": 4,
  "has_more": true,
  "next_offset": 4,
  "clusters_note": "clusters lists groups 1-4 of 9, ordered by how exactly the members match (exact, then near_exact, then similar), then by member count, then by how many services those members span. Re-call with offset: 4 to continue.",
  "clusters": [
    {
      "size": 3,
      "files": 3,
      "services": ["billing", "checkout"],
      "matched_on": "similarity",
      "exactness": "near_exact",
      "lowest_similarity": 0.96,
      "members_form": "expanded",
      "members": [
        {
          "repo": "billing-service",
          "services": ["billing"],
          "name": "slugify",
          "file_path": "src/text.ts",
          "line_number": 12,
          "end_line": 19,
          "intent": "Lowercases a string and replaces every run of non-alphanumeric characters with a single hyphen.",
          "similarity": 0.98
        }
      ]
    }
  ]
}

Audit results sort clusters by match quality (exactness), group size, and service breadth. exactness values include exact (identical descriptions or 3-decimal-place vector agreement), near_exact (exceeding near_exact_similarity), and similar. Clusters with more than expanded_members members format entries as compact locators (name, file_path, line_number).

`list_function_intents(service?, exclude_service?, limit?, offset?, typed_only?, name_contains?, intent_contains?)`

list_function_intents paginates through indexed functions and their generated intent descriptions for a service.

Parameters:

Name	Type	Required	Default	Notes
`service`	string	no		Restrict to one service.
`exclude_service`	string	no		Restrict to everything except one service.
`limit`	number	no	50	Max functions per page (max 200).
`offset`	number	no	0	Functions to skip before this page. Pass a previous response’s `next_offset` to page through.
`typed_only`	boolean	no	false	Only functions whose signature is fully explicit (every param and the return annotated).
`name_contains`	string	no		Case-insensitive substring filter on the function name.
`intent_contains`	string	no		Case-insensitive substring filter on the intent text.

Response shape:

{
  "total": 1247,
  "returned": 50,
  "offset": 0,
  "limit": 50,
  "has_more": true,
  "next_offset": 50,
  "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.",
      "typed": true,
      "reason": ""
    }
  ]
}

Service and graph exploration

`get_project_map(service?, detail?)`

get_project_map returns a plain-text summary of project services, dependencies, consumers, and unmatched calls. Use this tool at the start of an agent session to orient within the codebase.

Parameters:

Name	Type	Required	Notes
`service`	string	no	Your repo or service. The map then separates your repo from its siblings. Omit it to map the whole project.
`detail`	boolean	no	Shows about five times as many rows in each section. Use it when a section you need was cut short.

`list_projects()`

list_projects lists all projects in your workspace and the connected repositories belonging to each. It reads workspace metadata without loading scan data.

Response shape:

{
  "projects": [
    {
      "slug": "storefront",
      "display_name": "Storefront",
      "repos": ["acme/billing-service", "acme/checkout"]
    }
  ],
  "usage": "Pass `project: \"<slug>\"` (or `repo: \"<owner/repo>\"`) on the other Carrick tools to query that system."
}

`list_services()`

list_services returns every service in the project index along with endpoint, call, function, and intent metrics.

Response shape:

{
  "services": [
    {
      "repo_name": "billing-service",
      "service_name": "billing",
      "endpoint_count": 14,
      "call_count": 9,
      "function_count": 212,
      "intent_count": 205,
      "without_intent": { "single_line": 6, "other": 1 },
      "last_updated": "2026-05-24T19:02:11Z",
      "commit_hash": "a3f1c9d",
      "endpoint_types": true,
      "typed_functions": 188
    }
  ],
  "intent_coverage_percent": 97
}

endpoint_types: Set to true when a resolved .d.ts bundle exists for the service, allowing get_endpoint_types to return request and response types.
typed_functions: Counts functions whose parameter and return types are explicitly annotated.

`get_service_graph(service?, limit?, offset?)`

get_service_graph returns the cross-service call graph for a project, including consumer-producer edges across all protocols, unmatched client calls, and orphaned endpoints.

Parameters:

Name	Type	Required	Notes
`service`	string	no	Return only edges that touch this service (as consumer or producer), plus its unmatched calls and orphaned endpoints. Omit for the whole-project graph.
`limit`	number	no	Rows per array per page (default 40, max 200).
`offset`	number	no	Rows to skip in every array. Pass a previous response’s `next_offset` to read the next page.

Response shape:

{
  "services": [
    { "service": "checkout", "repo_name": "checkout", "endpoint_count": 8, "call_count": 6 }
  ],
  "edges": [
    {
      "consumer_service": "checkout",
      "producer_service": "billing",
      "protocol": "http",
      "method": "POST",
      "path": "/api/v1/invoices",
      "call_file_location": "src/billing/client.ts:31",
      "matched": true
    }
  ],
  "unmatched_calls": [],
  "orphaned_endpoints": [],
  "edge_count": 1,
  "unmatched_count": 0,
  "orphaned_count": 0,
  "matcher_version": "0.3.1"
}

Unmatched calls report a reason property:

external_target: The call targets an external or third-party domain.
base_unresolved: The call uses an unclassified environment variable or unresolved expression base.
base_unplaced: No service serves the path under the call’s method, and the call’s base is passed in at construction or is a loopback port no other call reaches, so the target service is unknown. check_compatibility reports it as a warning, not a missing endpoint.
no_matching_producer: The call targets an internal route not declared by any service.
producer_routeless: The target service exposes no declared routes or operations in the index.
dispatch_value_unknown: The call reaches a route whose handler switches on a request field, and the call does not state a value for that field.

Endpoints and type inspection

`get_operation(method, path, service?)`

get_operation finds all producer implementations, consumer call sites, and near-miss routes for a specific endpoint, GraphQL field, socket event, or pub/sub topic.

Parameters:

Name	Type	Required	Notes
`method`	string	yes	HTTP method (`GET`, `POST`, …), or a non-HTTP label from `get_api_endpoints` (`QUERY`, `MUTATION`, `CLIENT->SERVER`, `PUBSUB`). `UNKNOWN` matches a socket row whose direction the scan couldn’t read, and also an HTTP route whose verb it couldn’t read. Each returned row names its `protocol`.
`path`	string	yes	Route path, GraphQL field, socket event, or pub/sub topic. Placeholders in any style resolve (`:id`, `{id}`, `${expr}`). A `{field=value}` dispatch suffix, as the listings print it, narrows the producers to that one case and names the route’s other cases. Leave out the host, because internal operations are indexed by route path, not by URL.
`service`	string	no	Narrows the call-site sections (consumers, unmatched calls, consumer-side near misses) to one service. Producers stay project-wide.

Response shape:

{
  "requested": { "method": "GET", "path": "/api/v1/users/:id" },
  "producers": [
    {
      "service": "user-service",
      "protocol": "http",
      "method": "GET",
      "path": "/api/v1/users/:id",
      "file_location": "src/routes/users.ts:10"
    }
  ],
  "producer_count": 1,
  "consumers": [
    {
      "services": ["order-service"],
      "producer_service": "user-service",
      "protocol": "http",
      "method": "GET",
      "path": "/api/v1/users/:id",
      "call_file_location": "src/clients/userClient.ts:42"
    }
  ],
  "consumer_count": 1,
  "unmatched_calls": [],
  "unmatched_count": 0,
  "near_misses": {
    "note": "NOT the requested operation. ...",
    "neighbouring_path": [
      {
        "side": "producer",
        "services": ["user-service"],
        "protocol": "http",
        "method": "GET",
        "path": "/api/v2/users/:id",
        "file_location": "src/routes/usersV2.ts:8",
        "differs_by": "path segment \"v2\" where the requested operation has \"v1\""
      }
    ]
  },
  "matcher_version": "0.3.26"
}

The near_misses object reports routes differing by HTTP method (same_path_other_method) or by a single path segment edit (neighbouring_path), surfacing potential version mismatches or near-duplicate endpoints.

`get_callers(function_name, file?, depth?)`

get_callers identifies functions that call a specified function across the project.

Parameters:

Name	Type	Required	Notes
`function_name`	string	yes	Class members are named `Class.member`. `name` is accepted as an alias.
`file`	string	no	Path suffix of the file that defines the function. Use it when the name exists in more than one file.
`depth`	integer	no	How many call levels to walk back, from 1 (default) to 3. Above 1, each row includes the chain from that caller to the function.

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

get_api_endpoints lists all operations exposed by a service across HTTP, GraphQL, WebSockets, and pub/sub.

Parameters:

Name	Type	Required	Notes
`service`	string	yes	The service to inspect (fuzzy match by repo name, service name, or trailing segment).
`method`	string	no	Filter by operation label: HTTP method (`GET`, `POST`, …), GraphQL kind (`QUERY`, `MUTATION`, `SUBSCRIPTION`), socket direction (`CLIENT->SERVER`, `SERVER->CLIENT`, `UNKNOWN`), or `PUBSUB` for pub/sub topics. `UNKNOWN` also selects HTTP routes whose verb the scan couldn’t read. Each row names its `protocol`.
`path_contains`	string	no	Substring filter on the path, GraphQL field, event name, or topic.

Response shape:

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

`get_endpoint_types(service, method, path)`

get_endpoint_types returns the extracted TypeScript request and response types for an HTTP endpoint.

Parameters:

Name	Type	Required	Notes
`service`	string	yes	The service exposing the endpoint.
`method`	string	yes	HTTP method. A non-HTTP label (`QUERY`, `MUTATION`, `CLIENT->SERVER`, `PUBSUB`) is accepted but returns the redirect described above, not type text. `UNKNOWN` matches a socket row whose direction the scan couldn’t read, and also an HTTP route whose verb it couldn’t read. The HTTP route gets type text and the socket row gets the redirect.
`path`	string	yes	API path (matched against the service’s mount graph). A `{field=value}` dispatch suffix, as the listings print it, names one case of a dispatching route. A GraphQL field, socket event, or pub/sub topic is accepted but triggers the redirect.

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 }",
      "indexed_entries": 1
    },
    {
      "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 }",
      "indexed_entries": 1
    }
  ],
  "types_distinct": 2,
  "types_indexed_entries": 2
}

For non-HTTP protocols (GraphQL, WebSockets, pub/sub), this tool redirects to check_compatibility for pair-level compatibility verdicts.

`get_type_definition(service, type_alias)`

get_type_definition resolves the expanded TypeScript definition of a named interface or type alias.

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?, limit?, offset?)`

check_compatibility compares all outbound calls from a consumer service against the operations declared by a producer service, returning type-checking verdicts and mismatch diagnostics.

Parameters:

Name	Type	Required	Notes
`consumer_service`	string	yes	The service making the calls.
`producer_service`	string	yes	The service exposing the operations.
`method`	string	no	Filter by operation label: HTTP method, GraphQL kind, socket direction, or `PUBSUB`.
`path`	string	no	Filter by HTTP path, GraphQL field, socket event name, or pub/sub topic. A `{field=value}` dispatch suffix narrows to one case of a dispatching route.
`limit`	number	no	Issue rows per page (default 50, max 200). The tool cuts a page further when the response would be too long to read inline, and `issues_note` says when that happened.
`offset`	number	no	Issue rows to skip. Pass a previous response’s `next_offset` to read the next page.

Response shape:

{
  "consumer": "checkout",
  "producer": "billing",
  "status": "incompatible",
  "pairs_compared": 4,
  "pairs_uncompared": 1,
  "compatible": false,
  "types_checked": true,
  "types_checked_note": "types_checked is response-level: true means at least one matched pair carried a stored type-check verdict, not that every pair was verified. Per-pair coverage is in type_verdicts.",
  "verdict_source": "[email protected]",
  "type_verdicts": {
    "compatible": 3,
    "incompatible": 1,
    "unresolved": 0,
    "not_compared": 1
  },
  "consumer_calls": 6,
  "matched_calls": 5,
  "producer_endpoints": 14,
  "issues_total": 3,
  "issue_counts": {
    "missing_endpoint": 1,
    "type_incompatible": 1,
    "unused_endpoint": 1
  },
  "issues": [
    {
      "severity": "error",
      "category": "missing_endpoint",
      "message": "Consumer calls POST /api/v1/invoices/draft but producer has no matching endpoint",
      "call_file_location": "src/billing/drafts.ts:18"
    },
    {
      "severity": "error",
      "category": "type_incompatible",
      "message": "POST /api/v1/invoices: consumer's request body doesn't match the producer's CreateInvoiceRequest (field `amount` expected number, got string)"
    },
    {
      "severity": "info",
      "category": "unused_endpoint",
      "message": "Producer exposes DELETE /api/v1/invoices/:id but consumer doesn't call it"
    }
  ],
  "matcher_version": "0.3.1"
}

The top-level status evaluates overall pair compatibility:

compatible: All matched operations were compared and verified type-compatible.
incompatible: At least one call targets a missing operation or contains a type mismatch.
partially_checked: Compared operations match, but some pairs lack type verdicts.
unresolved: Operations could not be verified due to unextracted or dynamic types (any/unknown).

`get_service_dependencies(service?)`

get_service_dependencies identifies npm package version conflicts across services, or lists declared dependencies for a specific service.

Parameters:

Name	Type	Required	Notes
`service`	string	no	Omit for the project-wide conflict view.

Project-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,
  "packages": [
    { "name": "zod", "version": "3.22.4" }
  ]
}

`list_external_calls(service?, mechanism?, target?, view?, limit?, offset?)`

list_external_calls enumerates outbound calls made to third-party SDK packages, external HTTP domains, and environment-variable URLs.

Parameters:

Name	Type	Required	Notes
`service`	string	no	Limit to one service.
`mechanism`	string	no	`sdk`, `external_http` or `env_var_url`.
`target`	string	no	Part of a dependency name, hostname or environment variable name.
`view`	string	no	`targets` for one row per target instead of one per call site.
`limit`	integer	no	Rows per page, default 100, maximum 500.
`offset`	integer	no	Pass the `next_offset` from the previous page.

`get_contract_pair(consumer_service, producer_service, method?, path?, limit?, offset?)`

get_contract_pair displays side-by-side type definitions and stored compatibility verdicts for operations between a consumer and producer service.

Parameters:

Name	Type	Required	Notes
`consumer_service`	string	yes	The service making the calls.
`producer_service`	string	yes	The service serving the operations.
`method`	string	no	Narrow to one HTTP method.
`path`	string	no	Narrow to one route path as indexed. A `{field=value}` dispatch suffix, as the listings print it, narrows to that case.
`limit`	number	no	Operations per page (default 10, max 50).
`offset`	number	no	Operations to skip. Pass a previous response’s `next_offset` to read the next page.

Response shape:

{
  "consumer": "checkout",
  "producer": "billing",
  "operations": [
    {
      "operation": "GET /v1/invoices",
      "method": "GET",
      "path": "/v1/invoices",
      "producer": { "service": "billing", "request": null, "response": "T1" },
      "consumer": {
        "service": "checkout",
        "call_sites": [
          {
            "file_location": "src/Invoices.tsx:41",
            "call_path": "/v1/invoices",
            "expected_request": null,
            "expected_response": "T2"
          }
        ]
      },
      "call_site_count": 1,
      "untyped_sides": 0,
      "verdicts": [
        {
          "state": "unresolved",
          "scope": "pair",
          "scope_note": "One stored verdict covers the whole consumer/producer pair, not one call site: every call site listed on this operation shares it.",
          "consumer_key": "http|GET|/v1/invoices",
          "producer_key": "http|GET|/v1/invoices",
          "scanner_version": "0.3.60",
          "response": {
            "verdict": "unverifiable",
            "resolved": false,
            "unresolved_reason": "the producer surface export is missing or renamed"
          },
          "summary": "The response types were NOT compared: the producer surface export is missing or renamed."
        }
      ]
    }
  ],
  "operations_total": 12,
  "operations_shown": 10,
  "next_offset": 10,
  "types": [
    {
      "id": "T1",
      "type_aliases": ["Endpoint_9f2_Response"],
      "primary_type_symbol": "Invoice",
      "source_file": "src/routes/invoices.ts",
      "source_line": 22,
      "definition": "export interface Invoice { … }"
    }
  ],
  "consumer_calls_total": 31,
  "matched_calls": 24,
  "unmatched_calls": 7,
  "dropped_rows": 0
}

Repository onboarding

`scaffold()`

scaffold generates the configuration and workflow files required to onboard a repository onto Carrick:

.github/workflows/carrick.yml: The GitHub Actions workflow definition for continuous scanning.
carrick.json: The repository configuration defining services and classification lists.
.claude/skills/carrick/SKILL.md (or agent_memory_section for AGENTS.md/CLAUDE.md): Instruction rules guiding agent usage.

The response includes state indicators directing agent execution:

Field	Values	Action taken
`index_state`	`hosted`, `building`, `awaiting_collection`, `none`, `per_repo`, `unknown`	Indicates whether the repository already possesses a compiled index in Carrick Cloud.
`scan_step`	`ci`, `laptop`, `wait`, `resume`, `per_repo`	Determines whether the agent should run `carrick index --detach` locally or rely on CI.
`session_start_hook`	`check_local_settings`	Directs the agent to check `.claude/settings.json` to prevent registering duplicate start hooks.

Resources

MCP resources provide read-only data endpoints accessible directly by URI:

`carrick://services`

Returns the full service catalogue as a JSON array of service objects (matching list_services()).

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

Returns the complete bundled TypeScript declaration file (.d.ts) containing all exported types for the specified service.

Error handling and diagnostics

Tools return plain text in the content block when errors or empty results occur:

Missing service: Service "checkout" not found. Use list_services to see available services.
Unresolved project: A message prompting the agent to supply project or repo.
Unindexed project: A message stating that connected repositories have not yet been scanned.
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 responses that do not begin with { or [ as textual diagnostics.

Connecting your agent covers client configuration and agent prompt rules.
Task skills documents the four automated agent workflows.
Quickstart walks through initial setup and repository scanning.

MCP tools

Project scoping

Semantic search and code reuse

search_by_intent(query, also_phrased_as?, top_k?, similarity_threshold?, offset?, compact?)

Multi-phrasing queries

Threshold filtering and unindexed functions

find_similar(functions?, service?, min_lines?, similarity_threshold?, include_tests?, include_generated?, include_callbacks?, top_k?, limit?, offset?)

list_function_intents(service?, exclude_service?, limit?, offset?, typed_only?, name_contains?, intent_contains?)

Service and graph exploration

get_project_map(service?, detail?)

list_projects()

list_services()

get_service_graph(service?, limit?, offset?)

Endpoints and type inspection

get_operation(method, path, service?)

get_callers(function_name, file?, depth?)

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?, limit?, offset?)

get_service_dependencies(service?)

list_external_calls(service?, mechanism?, target?, view?, limit?, offset?)

get_contract_pair(consumer_service, producer_service, method?, path?, limit?, offset?)

Repository onboarding

scaffold()

Resources

carrick://services

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

Error handling and diagnostics

Related

`search_by_intent(query, also_phrased_as?, top_k?, similarity_threshold?, offset?, compact?)`

`find_similar(functions?, service?, min_lines?, similarity_threshold?, include_tests?, include_generated?, include_callbacks?, top_k?, limit?, offset?)`

`list_function_intents(service?, exclude_service?, limit?, offset?, typed_only?, name_contains?, intent_contains?)`

`get_project_map(service?, detail?)`

`list_projects()`

`list_services()`

`get_service_graph(service?, limit?, offset?)`

`get_operation(method, path, service?)`

`get_callers(function_name, file?, depth?)`

`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?, limit?, offset?)`

`get_service_dependencies(service?)`

`list_external_calls(service?, mechanism?, target?, view?, limit?, offset?)`

`get_contract_pair(consumer_service, producer_service, method?, path?, limit?, offset?)`

`scaffold()`

`carrick://services`

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