MCP endpoint reference

Authentication, protocol methods, results, and errors for repository MCP endpoints.

Each repository has a stateless, streamable HTTP endpoint:

POST https://api.thegarage.sh/api/repos/<namespace>/<repo>/mcp

<namespace> is the organization slug and <repo> is the repository name.

Published tools

The endpoint publishes built extensions from the repository’s default branch:

• modules in .garage/tools/ created with defineTool
• modules in .garage/extensions/ with dispatch: true

The endpoint lists a built but unpromoted extension, and that extension still runs. It receives no capabilities. Each call to repository data, records, or the network therefore fails at the capability gate. Promote the configuration before you rely on the output of a tool. See the extension model for the reason for this limit.

Authentication

Send a grg_ API key as a bearer token:

Authorization: Bearer grg_...

garage checks each request against one scope. The method selects the scope:

A client that discovers tools and calls them completes the initialize handshake first. Give that client a key with both scopes.

Protocol

Tool results

Successful calls include:

• structuredContent containing the tool output
• _meta.runId identifying the repository run

Inspect a run with:

garage runs get <run-id>
garage runs logs <run-id>

A tool that fails to run returns a tool result with isError: true. An invalid input also returns a tool result with isError: true. A malformed JSON-RPC request or an unknown tool returns a JSON-RPC error.

See Connect an MCP client for a complete client configuration.