MCP

MCP (Model Context Protocol) is a standard way for AI clients — Claude, Cursor, VS Code Copilot, and others — to call an app's features as tools. Point one of those clients at Openship and it can list your projects, kick off deployments, check logs, add domains, and more — using the exact same permissions you'd have yourself.

The important part: it's not a second, looser door into Openship. Every tool call re-runs the full auth and permission stack, so an agent can only ever see and do what its credential is allowed to — nothing more.

The endpoint

There's one endpoint, and it's the same on self-hosted and Openship Cloud:

POST /api/mcp

So on your instance that's https://<your-host>/api/mcp. A few things worth knowing up front:

• It's a stateless Streamable-HTTP JSON-RPC 2.0 endpoint — request in, response out.
• It's POST-only. A GET returns 405 (there's no server→client stream to open).
• No batching — send one JSON-RPC message per request, not an array.

You rarely type this URL by hand. Settings → MCP shows it pre-filled and gives you a copy button.

Connect a client

There are two ways to authenticate, and most clients pick one for you. Use the tab that matches your client.

claude mcp add --transport http openship https://<your-host>/api/mcp

codex mcp add openship --url https://<your-host>/api/mcp
codex mcp login openship

{
  "mcpServers": {
    "openship": {
      "url": "https://<your-host>/api/mcp",
      "headers": { "Authorization": "Bearer opsh_pat_…" }
    }
  }
}

claude mcp add --transport http openship https://<your-host>/api/mcp \
  --header "Authorization: Bearer opsh_pat_…"

Every call is re-checked

This is the heart of the security model, and it's why MCP access is as safe as your token:

• Authenticating once resolves your capability, but that's used only to filter tools/list — so a client isn't shown tools its token could never use.
• The real gate runs on every tools/call: the endpoint builds an internal request, forwards your bearer, and dispatches it through the same routes, validation, auth middleware, and per-resource permission check as a normal HTTP call.

The practical upshot: a read-only token can only reach read tools, and a scoped token stays boxed into its granted resources. A scoped token isn't even shown the org-wide list and create tools — get_projects (list every project) simply won't appear in its tools/list; it sees only the per-resource tools for the resource types it was granted. And if a tools/call touches something outside that scope, it comes back 404 — the scope doing its job. For the full protocol details (JSON-RPC methods, negotiation, error codes), see the MCP API reference.

The organization boundary applies to MCP exactly as it does to a browser session: because every call runs through the same per-resource permission check, an MCP client acts only within organizations you belong to and can never reach another org's projects, servers, or secrets — a resource outside your membership comes back 404, just as it would in the dashboard. See Isolation.

Which tools map to which API

Tools aren't a separate feature set — each one maps onto a permission-tagged REST route, and the tool name is built from that route's method and path. So get_projects is GET /api/projects, post_domains is POST /api/domains, and patch_projects_by_id is PATCH /api/projects/:id. Call tools/list to see the exact set your token can use.

Not every route is a tool: a route becomes one only when it opts in, so the set is a curated slice of the API rather than the whole surface. Each exposed tool also carries two hints a client can surface — readOnlyHint (the tool only reads) and destructiveHint (it deletes or tears something down) — so an agent UI can flag a destructive call before it runs.

Guided flows

Some tasks are a chain of calls in a specific order — deploying a repo, uploading a folder, installing a catalog app. The server ships a small set of prompts (prompts/list / prompts/get) that spell those chains out step by step, referencing the exact tools to call. Compatible clients surface them as slash-commands or starters, so an agent can pick a flow and follow it rather than reverse-engineering the order from the flat tool list. See the MCP API reference for the full catalog.

Verify from the terminal

To confirm a token works and see what it can do, ask for the tool list:

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

This returns exactly the tools that token is allowed to call.

If something goes wrong

Manage connected clients

Every OAuth client you've approved is listed under Settings → MCP → Connected clients, tagged with its access level (read-only or full control) and how many resources it can reach. Disconnect revokes the client's issued tokens immediately and drops its consent, so it has to re-authorize next time. The same list and controls are available programmatically via the Tokens API.

What next?