MCP API

The MCP API is a single Model Context Protocol endpoint that lets AI agents (Claude, Cursor, and any MCP-compatible client) drive Openship as a set of tools. Each tool maps onto a permission-tagged REST route, and every call re-runs the full auth and permission stack — so an agent only ever sees and does what its token allows. For client setup (OAuth flow, config snippets), see the MCP overview.

Available on both self-hosted and Openship Cloud (mounted in the shared route set).

Endpoints

Both routes are declared public (no auto-injected auth middleware): the POST handler authenticates the bearer credential itself, and each tools/call dispatches an internal request that re-authenticates through the real permission stack.

How authentication works

A missing or invalid bearer returns 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource, so OAuth-2.1 MCP clients can discover the authorization server and start the PKCE flow. A valid credential resolves the caller's effective capability — this is used only to filter tools/list so the endpoint doesn't advertise tools the token can't use.

The capability is not the authorization gate. Every tools/call builds an internal HTTP request and dispatches it through the real Hono app, forwarding the caller's bearer, so routing, validation, auth, and the per-resource permission check all run exactly as they do over HTTP. A read-only token can only reach read tools; a scoped token stays confined to the projects, servers, and repositories it was granted.

The endpoint is rate-limited per-IP (the mcp policy: 300 requests/minute) because even an unauthenticated probe costs a credential lookup.

Request body (JSON-RPC 2.0 envelope)

The POST body is a single JSON-RPC 2.0 message (batching was removed in protocol 2025-06-18 — an array body returns -32600).

Methods

List available tools

POST /api/mcp

curl -s https://your-host/api/mcp \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Register the same endpoint with an MCP client (Claude Code):
claude mcp add --transport http openship https://your-host/api/mcp \
  --header "Authorization: Bearer $OPENSHIP_TOKEN"

The tool set is derived from Openship's permission-tagged routes that opt in with an mcp block; the credential/auth surfaces (tokens, auth, mcp itself) are never exposed.

Call a tool

params.name is the tool name from tools/list; params.arguments carries any path parameters, an optional query object, an optional body object (for POST/PUT/PATCH tools), and an optional organizationId (sent as the x-organization-id header).

curl -s https://your-host/api/mcp \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_projects","arguments":{}}}'

The result wraps the underlying API response as text content, with isError: true when the dispatched request failed.

Guided flows (prompts)

tools/list is flat — it tells an agent what each tool does, one call at a time, but not how the multi-step flows chain together. The prompts catalog fills that gap: each prompt is a short, ordered playbook for a workflow, referencing the exact tool names to call in sequence. MCP clients surface them as slash-commands / starters, so they also serve as the discoverable entry points into a flow.

curl -s https://your-host/api/mcp \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"prompts/get",
       "params":{"name":"deploy-from-git","arguments":{"repo":"acme/widgets"}}}'

Prompt text resolves tool references against the live registry, so a renamed route never leaves a prompt pointing at a stale tool name.

Errors you might see