Authorization
The hosted MCP server uses OAuth and enforces a reviewed workspace, mode, connection set and scopes. Browser consent requires one workspace, Test or Live, and an explicit connection selection. Changing the workspace or mode clears the previous selection before a new review.
OAuth only
Never paste a Seamward browser cookie or a collector ingest token into an MCP client. The MCP server rejects both. The only accepted credential is the short-lived token issued by the approval flow described here.
How authorization works
When a client first contacts the MCP server without a token, the server replies with a pointer to its published authorization metadata. The client can register automatically and begin the standard OAuth flow (authorization code with PKCE). The browser binds your exact mode and connection selection before approval. An empty selection permits workspace metadata without connection evidence.
One grant binds exactly one user, one client, one workspace, one canonical mode, and the reviewed connection IDs. On every request, Seamward revalidates the token's signature, issuer, audience, current workspace membership, active consent, and review revision. A changed or removed connection invalidates the reviewed grant until it is renewed. The client cannot read a connection in another mode merely because it belongs to the same workspace.
Scopes
The consent screen lists the scopes a client requests. Approve only what the client's job needs:
| Scope | Unlocks |
|---|---|
seamward:workspace:read | get_workspace_overview, list_integrations, get_integration |
seamward:incidents:read | list_incidents, get_incident |
seamward:repairs:read | get_incident_replay, get_repair_proposal |
seamward:repairs:export | get_approved_repair_bundle and the export file resources |
By default, clients request the first three read scopes. The export scope is never included implicitly: a client that should retrieve approved repair bundles must request seamward:repairs:export, and you must approve it. Clients may also request offline_access to refresh tokens in the background instead of asking you to re-approve every 15 minutes.
Token lifetimes
| Credential | Lifetime | Notes |
|---|---|---|
| Authorization code | 5 minutes | Single use, exchanged during approval |
| Access token | 15 minutes | Signed and bound to your exact MCP server URL |
| Refresh token | Until revoked | Only when you approve offline_access |
Access tokens are audience-bound: a token issued for your hosted MCP server URL is useless anywhere else. This hosted workspace MCP does not use long-lived API keys. The local automatic setup MCP uses a separate browser authorization bound to one exact workspace environment, and stores its short-lived credential outside the repository.
For automatic project setup, the consent screen selects one workspace and one environment. The setup agent then previews every Integration it would create or reuse in that environment before a separate remote approval.
Revocation
Open Workspace settings → MCP to see authorized clients, their reviewed mode and connections, scopes, and connection date. Choosing Revoke immediately rejects already-issued tokens on their next request, not just at expiry. Renew authorization to change the mode or connection set; a prior consent does not silently widen to newly created connections.
Access also ends automatically when your workspace membership ends, because membership is revalidated on every request.
Safety boundary
The grant model enforces hard limits that no scope combination can lift:
| An MCP client can never | Because |
|---|---|
| Approve, merge, or deploy a repair | No write tools exist; approval stays an explicit decision in the console |
| Read raw request or response payloads | Evidence is redacted before it is stored; raw values are never kept |
| Read provider credentials or GitHub tokens | Secrets are excluded from every evidence view |
| Invite members or change workspace settings | No member, credential, or workspace mutations are exposed |
| Reach another workspace, mode or connection | Grants bind to the reviewed selection; other ids return not_found |
| Authenticate with an ingest token or cookie | The server accepts only its own OAuth tokens |
Next steps
- MCP overview: connect and approve a client.
- Resources and tools: what each scope's tools return.