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 also lists built, unpromoted extensions. They can run, but receive only capabilities both requested by that version and granted to the same name in the promoted configuration. Without a promoted entry of that name, they receive no capabilities: repository data, records, and network calls fail at the capability gate. Promote the configuration to grant the requested access. 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.