MCP server

Stable project resources, OAuth, internal sessions, tools, revocation, and advanced API-key access.

Stacklink exposes a primary OAuth-protected resource for installed AI clients and retains a separate advanced API-key route for applications that explicitly manage a session.

Endpoint ownership

Endpoint	Purpose	Authentication	Session ID visible?
`POST /v1/mcp/projects/:publicSlug/clients/:clientKey`	Primary Cursor, VS Code, Claude, Codex, and remote-client installation	MCP OAuth access token	No
`POST /v1/sessions/:sessionId/mcp`	Explicit advanced machine setup for an already-created SDK session	Stacklink API key	Yes, by design

The project/client URL is immutable public connector identity. The slug is not a secret. OAuth binds the token to the exact project resource, user, client registration, grant, scopes, and approved installation.

OAuth discovery

An unauthenticated request receives 401 Unauthorized and a WWW-Authenticate header pointing to the protected-resource document. Stacklink exposes:

OAuth protected-resource metadata for the exact project/client URL.
Authorization-server metadata.
Client ID Metadata Document support.
Pre-registered certified clients where available.
Dynamic client registration as a compatibility fallback.
Authorization, token, refresh, and revocation endpoints.

Every authorization-code flow requires PKCE S256, exact redirect URI matching, and the exact resource value. Access and refresh tokens are short-lived, stored hashed by Stacklink, rotated, and individually revocable. Refresh-token reuse revokes the token family and installation session.

Connection lifecycle

launch intent created
→ authorization_started
→ authorized
→ authenticated initialize
→ handshake_pending
→ notifications/initialized
→ tools/list
→ connected

The launch intent exists only to report Overview progress. It is not a credential and owns no runtime session.

OAuth approval creates or updates the durable installation and grant.
Token exchange does not create a runtime session.
First authenticated initialize creates or resumes the installation's internal session.
notifications/initialized records client readiness.
First successful tools/list marks the installation connected.
Revocation closes the exact bound session.

Methods

Method	Behavior
`initialize`	Validates the OAuth resource and creates or resumes the internal installation session
`notifications/initialized`	Records that the client accepted the negotiated server capabilities
`ping`	Health check
`tools/list`	Returns the connector tool surface with no caller-visible `sessionId`
`tools/call`	Injects the installation's internal session before validation and execution
`notifications/cancelled`	Cancels an in-flight streamed call where supported

The protocol version defaults to 2025-11-25.

Tool boundary

The primary installed-client resource exposes the connector tool surface only. Project administration, API-key management, billing, Memory, Knowledge administration, and other privileged surfaces require their own explicit contracts and scopes.

Stacklink provider permissions and approval rules remain authoritative. OAuth grants access to the Stacklink MCP resource; it does not bypass provider-account authorization or mutation approvals.

Streaming

Long-running calls can use Server-Sent Events when the client requests text/event-stream and supplies a progress token. Stacklink emits bounded progress notifications and heartbeats while execution continues.

If the client does not support progress streaming, normal JSON-RPC requests continue to work for operations that complete within the request window.

Security invariants

No API key, OAuth token, refresh token, provider token, or session ID is placed in an installation URL.
Access tokens are accepted only for their exact Stacklink resource audience.
Redirect URIs and client identifiers are matched exactly.
Runtime sessions are looked up by installation ID, never by fuzzy names or prefixes.
Returned tool schemas for installed clients do not contain sessionId.
Revoked, expired, wrong-project, and refresh-reused credentials fail closed.
Provider credentials never receive or transit MCP client OAuth tokens.

Advanced API-key route

The session-scoped route remains available for deliberate machine configuration. The application creates the SDK session and authenticates with a Stacklink API key. Do not use that route for the primary Overview app buttons, and do not place its credentials inside a one-click installation link.

For the human setup path, see Connect your agent. For SDK-owned sessions and complete harness loops, see the TypeScript and Python recipes.

On this page