Connect your agent

Use this path when your AI app supports remote MCP. You do not create a Stacklink session or API key before connecting.

Stable workspace connector URL
→ Stacklink OAuth
→ choose allowed projects
→ authenticated initialize
→ tools/list
→ Connected

The connector URL identifies one Stacklink workspace and one client type. It is safe to place in an installation link because it contains no API key and no runtime session ID, OAuth token, or provider secret.

One AI app connection can use several projects in that workspace. Stacklink grants only the projects selected during consent. It does not automatically grant current or future projects.

Start from Stacklink Overview

1. Open the project Overview.
2. Select Connect an app.
3. Choose Cursor, VS Code, Claude, or Codex.
4. Approve adding Stacklink in the client.
5. Sign in to Stacklink and choose the projects this client may use. The project you started from is selected by default.
6. Wait until the client completes initialize and tools/list.

Overview shows Connected only after Stacklink receives the real authenticated protocol events. Opening an app or completing a browser redirect is not treated as proof of connection.

Client behavior

CursorVS CodeClaudeCodexOther client

Choose Add to Cursor in Overview. The installation link contains only the stable Stacklink resource URL. Cursor displays its own server review screen, discovers Stacklink OAuth, and opens the Stacklink consent page.

Stacklink names the saved server for your workspace. Use Add this project from another project Overview to extend the same connection instead of installing another Cursor server. If the installation link is blocked, choose Manual setup in Overview and copy the generated HTTP MCP configuration.

Choose Install in VS Code in Overview. VS Code reviews the workspace Streamable HTTP server definition before saving it. Authentication then uses the same Stacklink OAuth flow.

If VS Code is not installed, install it first and retry the Overview action. Stacklink does not treat opening the vscode: URI as connection proof.

Choose Add to Claude. Stacklink opens Claude's official custom-connector review form with both fields prefilled:

• Connector name: Stacklink — <workspace name>
• Connector URL: the stable workspace- and Claude-scoped Stacklink URL

Choose Add in Claude, then complete Stacklink sign-in. The optional Open Claude Desktop action opens Claude Desktop separately; connector settings themselves are completed in the official web form. The resulting remote connector is also available in Claude Desktop.

If Claude is already connected to the workspace but not the selected project, Overview shows Add this project. Approving that action extends the existing workspace connection and does not create a second Claude connector. Use Manage access to remove a project without disconnecting the other authorized projects.

Claude connects from Anthropic's cloud, so the Stacklink endpoint must use public HTTPS. It cannot connect to a localhost-only server. Team and Enterprise workspaces may require an owner to add the connector before individual members authenticate.

Choose Copy Codex MCP URL. In Codex Settings, add a Streamable HTTP MCP server using the workspace name shown by Overview, paste the URL, save it, and choose Authenticate. Restart the client if Codex asks you to reload MCP configuration.

The desktop app, CLI, and IDE extension share Codex MCP configuration. Keep terminal commands under advanced setup; the primary Overview action remains app-oriented.

Choose Other MCP client under advanced setup and copy the stable resource URL. The client must support Streamable HTTP and the MCP OAuth discovery flow.

Stacklink calls a client certified only after its exact installation, OAuth, initialize, tools/list, harmless tool call, revocation, and reconnect flow has passed on staging.

Authentication and sessions

The client first contacts Stacklink without a token. Stacklink returns 401 Unauthorized with protected-resource metadata. The client discovers the authorization server, uses authorization code plus PKCE, and receives a workspace-resource OAuth token after consent.

The token is stored by the MCP client. After authenticated initialize, Stacklink creates one internal runtime session for each authorized project. The session is resolved from the exact installation and project reference; there is no shared mutable “current project.” Session IDs remain backend plumbing and never appear in the installed client configuration or tool schemas.

The workspace tool surface starts with STACKLINK_LIST_PROJECTS. Every project-owned Stacklink tool then requires the exact opaque projectRef returned by that call:

await STACKLINK_SEARCH_TOOLS({
  projectRef: "opaque-project-reference",
  queries: [{ id: "email", task: "Find unread support emails" }],
});

Stacklink never guesses a project from a display name. If the user has not identified the project, the agent should ask which authorized project to use.

Connect only this project

For production agents or stricter isolation, choose Connect only this project under advanced setup.

In project-scoped mode:

• the token can access only that project;
• STACKLINK_LIST_PROJECTS is not exposed;
• Stacklink injects the project internally;
• project arguments are not shown to the client.

SDK API keys remain project-scoped and are not changed by the workspace MCP connection model.

Provider accounts are separate

Connecting the AI app proves that the client can see Stacklink tools. It does not automatically connect Gmail, Slack, Linear, or other provider accounts.

When a tool needs a provider account that is not connected, Stacklink returns a connection-required result. Complete that provider's authorization flow, then retry the tool. See Connect an account.

Revoke or reconnect

Use Remove this project to revoke only the selected project and close its bound runtime session. Other authorized projects stay connected. Disconnecting the workspace installation invalidates the client grant and closes every project session under it.

If setup is cancelled before authenticated initialize, Stacklink leaves no unused runtime session. An abandoned launch intent expires automatically.

Overview distinguishes four exact states:

• Green: the workspace client is connected and the selected project is authorized.
• Amber: the workspace client is connected, but the selected project is not authorized.
• Reconnect: this project's saved grant is revoked or its MCP handshake is incomplete.
• No badge: this client has no saved workspace or project connection.

Troubleshooting

For protocol details, continue to MCP server.