MCP

Openship exposes a Model Context Protocol (MCP) endpoint so AI agents (Claude, Cursor, and any MCP-compatible client) can manage your deployments, projects, and infrastructure as tools. It's the same permission model as the REST API — an agent only ever sees what its token is allowed to.

Endpoint

POST /api/mcp

Openship Cloud: https://api.openship.io/api/mcp
Self-hosted: https://<your-api-host>/api/mcp

It's a stateless Streamable-HTTP JSON-RPC 2.0 endpoint. It's POST-only — a GET returns 405 (there's no server→client streaming), and JSON-RPC batching is not supported.

Settings → MCP in the dashboard always shows the exact URL for your instance, plus a ready-to-paste client config.

Connecting

There are two ways to authenticate, and most clients pick automatically:

OAuth (recommended — auto-discovery)

Openship is a standards-compliant OAuth 2.1 MCP server. Clients that support it (Claude, Cursor, …) just take the endpoint URL and handle the rest: an unauthenticated request gets a 401 pointing at /.well-known/oauth-protected-resource, the client registers itself dynamically, runs the PKCE authorize flow, and you approve it on a consent screen in your browser. No copy-pasting credentials.

On that consent screen you choose exactly what the client may do — read-only and/or a specific set of projects, servers, and repositories. That scope is enforced through the same grant model as a scoped Personal Access Token: the client can never exceed what you granted, or what you can access yourself.

In a client that asks for an MCP server URL, just give it:

https://api.openship.io/api/mcp

Personal Access Token (manual / API-key)

For clients without OAuth support — or for a narrowly-scoped, long-lived token — authenticate with a PAT as a bearer credential.

Authentication

Authenticate with a Personal Access Token as a bearer credential — there's no separate MCP credential:

Authorization: Bearer opsh_pat_…

Create one under Settings → Tokens. Every tool call re-runs the full permission stack, so the token's limits are enforced on each request:

Read-only token → the agent can only call read tools.
Scoped token → the agent is confined to exactly the projects, servers, and repositories you grant it, even below your own role.

For agents, mint a narrow, scoped (or read-only) token rather than handing over your full access.

Client config

Any MCP client that accepts an HTTP server URL with headers:

{
  "mcpServers": {
    "openship": {
      "url": "https://api.openship.io/api/mcp",
      "headers": { "Authorization": "Bearer opsh_pat_…" }
    }
  }
}

Claude Code

claude mcp add --transport http openship https://api.openship.io/api/mcp \
  --header "Authorization: Bearer opsh_pat_…"

Swap the URL for your own host if you're self-hosting, and replace the token.

Verify

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

This returns the list of tools the token can use.

401 Invalid or expired access token → the token is wrong or revoked.
A tools/list that succeeds but a specific tools/call returns 404 for a resource → that's the token's scope doing its job: it wasn't granted that resource.

Available tools

Tools are derived from Openship's permission-tagged API routes, so the set an agent sees matches its token's permissions. Call tools/list to enumerate exactly what a given token can do.

On this page