MCP Server

WarmHub implements the Model Context Protocol (MCP) over HTTP, exposing all read and write operations as typed tools that AI agents can discover and call.

Protocol

• MCP version: 2024-11-05
• Server name: warmhub-next-mcp
• Transport: JSON-RPC 2.0 over HTTP POST
• Supported methods: initialize, tools/list, tools/call, ping

Endpoints

Method	Path	Description
POST	/mcp	Global MCP endpoint
GET	/mcp	Returns 405 Method Not Allowed
POST	/mcp/:org/:repo	Repo-scoped MCP endpoint
GET	/mcp/:org/:repo	Returns 405 Method Not Allowed

Global vs Repo-Scoped

Global Mode (POST /mcp)

The global endpoint exposes the full MCP tool catalog. Repo-level tools require orgName and repoName arguments. It also includes org-level tools:

• warmhub_org_list
• warmhub_org_get
• warmhub_org_set_description
• warmhub_org_archive
• warmhub_org_unarchive
• warmhub_repo_list
• warmhub_repo_create

Best for agents that work across multiple repos.

Repo-Scoped Mode (POST /mcp/:org/:repo)

Org and repo are baked into the URL. Tool schemas omit orgName/repoName parameters, and org-level tools are excluded.

Best for agents that focus on a single repo — simpler tool schemas, fewer required arguments.

Configuration

MCP Client Setup

Add a WarmHub entry to the mcpServers section of your MCP client’s configuration. The examples below use the standard format supported by Claude Desktop, Cursor, and other MCP-compatible clients. The transport field is required by some clients (e.g., Claude Desktop); others infer it from the URL scheme.

Repo-scoped (recommended):

{
  "mcpServers": {
    "warmhub": {
      "transport": "http",
      "url": "https://api.warmhub.ai/mcp/myorg/myrepo"
    }
  }
}

Global (multi-repo):

{
  "mcpServers": {
    "warmhub": {
      "transport": "http",
      "url": "https://api.warmhub.ai/mcp"
    }
  }
}

The examples above use the production API URL. For self-hosted deployments, replace api.warmhub.ai with your deployment URL.

Tool Responses

Tool responses include both human-readable and structured content:

{
  "content": [{ "type": "text", "text": "..." }],
  "structuredContent": { ... },
  "isError": false
}

• content — tool result as text for the model-readable channel. Typically JSON, but unauthenticated responses may include a trailing prose annotation (see Authentication Awareness below).
• structuredContent — typed object for programmatic access. Includes an auth field on every response (see below).
• isError — true if the tool call failed

Read-only tools are annotated with readOnlyHint: true in their tool definitions.

Authentication Awareness

Every tool response includes structuredContent.auth with the caller’s authentication status:

// Authenticated
{ "structuredContent": { "items": [...], "auth": { "authenticated": true } } }

// Unauthenticated
{ "structuredContent": { "items": [...], "auth": { "authenticated": false, "hint": "Showing public data only. Authenticate to include private orgs and personal data." } } }

When unauthenticated, the content text channel also appends a bracketed note after the result data:

[{"name":"acme"}]

[Not authenticated. Showing public data only. Authenticate to include private orgs and personal data.]

Read-only tool descriptions include an auth awareness note at runtime, instructing agents to suggest authentication when expected data is missing.

Error Handling

Backend errors are mapped to MCP JSON-RPC error codes:

• Unknown tool name → invalidParams error
• Missing required arguments → invalidParams error
• Backend validation errors → tool response with isError: true and structured error content
• NOT_FOUND errors → tool response with error details. When the caller is unauthenticated, the error message includes an auth hint: “This resource may be private — authenticate to access private orgs and repos.”

Tool execution errors return the error in the tool response (not as a JSON-RPC error), following the MCP convention that tool errors are “expected” failures. Error responses also include structuredContent.auth with the caller’s authentication status.

For backend write failures, inspect the structured error metadata in the tool response. WarmHub includes the backend error code when available, for example backendCode: "RATE_LIMITED" on rate-limited write tools such as warmhub_commit_apply or warmhub_subscription_create.

When a tool returns backendCode: "RATE_LIMITED", clients should treat it as retryable and apply backoff before retrying the tool call. MCP tool errors do not currently expose the HTTP Retry-After header, so clients should use their own bounded retry policy.

Repo-Scoped 404

When a repo-scoped endpoint (/mcp/:org/:repo) cannot resolve the org or repo, it returns HTTP 404. For unauthenticated callers, the response body includes an auth hint: Not Found. This resource may be private — authenticate to access private orgs and repos. Authenticated 404s return a plain Not Found body.