Skip to main content
Shipstar’s backend is a full OAuth 2.1 authorization server. Off-the-shelf MCP clients — claude.ai custom connectors, Claude Code, Claude Desktop — handle the whole flow automatically: add the server URL, sign in, pick a project, done. The first half of this page covers that; the second half is protocol detail for people building their own client or debugging a connection.

​
Connecting from claude.ai (custom connector)

  1. In claude.ai, go to Settings → Connectors → Add custom connector and enter:
  2. Click Connect. Your browser opens Shipstar’s consent page (sign in first if needed).
  3. Pick the project the connection should operate on — every authorization is scoped to exactly one Shipstar project — and approve.
  4. You’re returned to claude.ai with the 23 Shipstar tools available in any chat.
To operate on a different project, add another connector authorization (or re-authorize) and choose the other project at consent time. You can revoke a connection at any time from the Shipstar dashboard or by removing the connector in claude.ai. Claude Code uses the same flow without any token handling:
Prefer a static token for scripts or CI? Dashboard API tokens work as plain bearer tokens on the same endpoint — see the MCP overview.

​
Discovery

Standard metadata at the mcp.shipstar.ai domain root, also served with the resource path appended (RFC 8414 / RFC 9728 path-insertion):
The OAuth endpoints themselves live on the API host (https://api.shipstar.ai/oauth/...), as advertised in the metadata — both hostnames are served by the same backend, so the documents resolve on either. Endpoints: /oauth/authorize, /oauth/token, /oauth/register, /oauth/revoke. Unauthenticated requests to /mcp return 401 with a WWW-Authenticate challenge pointing at the protected-resource metadata, so spec-compliant clients bootstrap the flow from a bare URL.

​
Client registration

Dynamic client registration (RFC 7591) is open — POST /oauth/register with your client metadata (rate-limited per IP). Redirect URIs must match exactly at authorization time. Public clients (token_endpoint_auth_method: "none", the default) are supported for native/desktop apps; confidential clients receive a client_secret (stored hashed, client_secret_expires_at: 0 = non-expiring). Client auth at /token is accepted as form parameters or HTTP Basic.

​
Authorization

  • PKCE S256 is required on every authorization request (code_challenge_method=S256; plain is rejected).
  • /oauth/authorize does not itself log the user in: it validates the request, then redirects to Shipstar’s consent page (app.shipstar.ai/oauth/authorize), which is login-gated. The consent page shows your client’s name and logo and asks the user to select a project — the minted grant is scoped to that project.
  • On approval the user agent returns to your redirect URI with code + state; denial returns error=access_denied.
  • Consent tickets expire after 10 minutes; authorization codes expire after 10 minutes and are single-use.

​
Scope

A single scope: mcp. It is granted by default when unspecified and covers all 23 tools. Effective access control is the per-project grant chosen at consent — a token can only ever see the one project it was authorized for.

​
Tokens

Tokens are opaque (not JWTs) and stored hashed server-side. Refresh rotation is strict with replay detection: each refresh revokes the old pair and issues a new one, and presenting an already-revoked refresh token revokes the entire token chain for that grant. Store the new pair from every refresh response.

​
Revocation

RFC 7009 POST /oauth/revoke — always returns 200, even for unknown tokens. Expect calls to start failing with 401 at any time (user revocation, chain revocation after replay); re-run the authorization flow to reconnect.