MCP server

Workspace and 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/workspaces/:publicSlug/clients/:clientKey`	Primary multi-project Cursor, VS Code, Claude, Codex, and remote-client installation	MCP OAuth access token	No
`POST /v1/mcp/projects/:publicSlug/clients/:clientKey`	Restricted installation for one project	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 workspace/client and project/client URLs are immutable public connector identities. Their slugs are not secrets. OAuth binds each token to the exact 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 workspace/client or 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 every session owned by the installation.

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 one internal session for each authorized project.
notifications/initialized records client readiness.
First successful tools/list marks the installation connected.
Removing one project closes its exact session; installation revocation closes every bound project session.

Methods

Method	Behavior
`initialize`	Validates the OAuth resource and creates or resumes the installation's authorized project sessions
`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`	Resolves the exact authorized project and injects its 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 workspace resource exposes STACKLINK_LIST_PROJECTS plus the connector tool surface. Every project-owned tool requires the opaque projectRef returned by STACKLINK_LIST_PROJECTS. Stacklink resolves operations by installation ID + projectRef; it does not keep a mutable current project or match project names.

The restricted project resource omits STACKLINK_LIST_PROJECTS and injects its single project internally. 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 plus exact project reference, never by fuzzy names or prefixes.
Workspace tokens can use only project grants explicitly approved by the dashboard user.
Project membership and grant access are checked again while the token is used.
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