MCP Server

AgentStack exposes a Model Context Protocol server scoped to your active organization. Once connected, your MCP client (Claude Code, Claude Desktop, Codex, and others) can read agents, sources, and conversations. The client can also run admin operations, such as creating agents, running tests, and adding sources. You do not need to add an organization ID to each call.

Server URLCopy Anchor Link

Use the streamable HTTP endpoint:

https://www.agentstack.build/api/mcp

The MCP Server screen in your workspace dashboard shows the exact URL. You can also copy a ready-made configuration for each client from that screen.

Connect to part of the serverCopy Anchor Link

The default URL gives the client every tool. Two other forms narrow that:

These toolsets mount dedicated tools: agents, analytics, apikeys, catalog, contacts, conversations, inbox, members, organizations, and sources. Separate several with commas, as in /api/mcp/x/inbox,agents. A client that can send a custom header can select the same list with X-MCP-Toolsets on /api/mcp. The path form ignores that header, so the path wins when you use both.

A toolset name is also a gate on the catalog tools. The catalog tools mount under every selection, but they refuse an operation whose toolset you did not select. These toolsets have no dedicated tools and are reachable only through the catalog: actions, activity, auditlogs, billing, channels, conversation notes, customdomains, customroles, helpcenter, helppage, ingest, messages, notion, topics, voice, and webhooks. Name one of them to let the catalog reach it, as in /api/mcp/x/inbox,billing. The name conversation notes has a space, so percent-encode it in the path or use the header form.

Use a narrow connection to keep a client's tool list short and focused. AgentStack applies the selection on the server, so an unselected tool is never offered. /api/mcp/readonly is a real restriction, not a hint: the client cannot write, even with a write scope on its token.

AuthenticationCopy Anchor Link

AgentStack uses OAuth through Better Auth. The first time a client connects, AgentStack opens a browser window for sign-in. You approve the scopes: read-only or write. The client then stores a refresh token. A successful refresh issues a new access token and refresh token. The refresh token the client sent keeps working for 60 seconds after its first use, so two refreshes that run at the same time both succeed. If the client presents that refresh token again after the 60 seconds, AgentStack treats it as reuse: it revokes every token that the client holds for that user, the refresh fails with invalid_grant, and the user must authorize the client again. If AgentStack cannot complete a refresh, it answers 500 with server_error and keeps no new tokens; the refresh token the client sent still works, so the client can retry the same refresh. Tokens are scoped to your user account. The organization that is active at the time of authorization is the organization that the tools operate on.

ScopesCopy Anchor Link

The MCP endpoint requires at least one MCP scope on the access token:

Clients can also request the standard openid, profile, email, and offline_access scopes. The server publishes every supported scope in its discovery documents (/.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource). A spec-compliant client requests them automatically, so you do not need to configure anything. A client that requests no scopes at all is granted read and write access, but not mcp:send, mcp:admin, mcp:billing or mcp:chat. You still approve this access on the consent screen. See MCP scopes for the full reference.

The scopes that you approve stay fixed for the life of that token. To change the scopes, remove the client and reauthorize it. AgentStack remembers what you approved for each client: if you are signed in and the client asks again for the same scopes or fewer, the consent screen is skipped. If it asks for a scope that you have not approved, the screen appears again.

The same scopes apply when the token is used on the REST API at /api/v1. A token can never do more on the REST API than on the MCP endpoint. See REST API authentication for the scope each REST endpoint needs. The one scope with no MCP tool is mcp:chat: it opens the REST chat endpoints, POST /api/v1/chat and POST /api/v1/chat/stream.

When a client disconnects, it can revoke its own tokens at /api/auth/mcp/revoke (RFC 7009). The discovery document advertises this address as revocation_endpoint, so a spec-compliant client finds it without configuration. Revoking any one token, access or refresh, revokes every token that the client holds for that user. After revocation, the client's next call to the MCP endpoint is refused, its refresh tokens no longer work, and the user must authorize it again. If the same user connected the same client more than once, all of those connections are revoked. Revocation does not forget the approval: when a signed-in user authorizes the same client again for the same scopes, the consent screen is not shown.

InstallCopy Anchor Link

The settings page shows the right snippet for your client. Use this quick reference:

Claude CodeCopy Anchor Link

Claude Code connects to the streamable HTTP endpoint directly. Run this in your terminal:

claude mcp add --transport http agentstack https://www.agentstack.build/api/mcp -s user

Claude DesktopCopy Anchor Link

Claude Desktop adds AgentStack as a custom connector. No config file is needed.

1. Open Claude Desktop → Settings → Connectors.
2. Click Add custom connector.
3. Paste https://www.agentstack.build/api/mcp and click Add.
4. Sign in and approve read-only or write access in the browser.

As an alternative, route the connection through the mcp-remote relay. Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%/Claude/):

{
  "mcpServers": {
    "agentstack": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://www.agentstack.build/api/mcp"]
    }
  }
}

CodexCopy Anchor Link

The Codex app, the Codex CLI and the IDE extension share one config file, so you only add the server once.

In the Codex app:

1. Open Settings → MCP servers.
2. Click Add server.
3. Name it agentstack and choose Streamable HTTP.
4. Paste https://www.agentstack.build/api/mcp in the URL field, then save.
5. Click Restart, then Authenticate to sign in.

Or run this in your terminal. It writes the same ~/.codex/config.toml the app reads:

codex mcp add agentstack --url https://www.agentstack.build/api/mcp

Other clientsCopy Anchor Link

Cursor, VS Code, Gemini CLI, Windsurf, OpenCode, Zed, Warp, v0, Kiro, Roo Code, and most other MCP-compatible clients accept the standard mcpServers block. Use the direct URL form first. If your client supports only stdio, use the mcp-remote relay instead.

{
  "mcpServers": {
    "agentstack": {
      "url": "https://www.agentstack.build/api/mcp"
    }
  }
}

What you getCopy Anchor Link

• Read agents, sources, conversations, contacts, teams, and analytics.
• Create and update agents, run agent tests, add URL or text sources, and restore soft-deleted records.
• Work Help Desk tickets: list, inspect, assign, note, close, and reply.
• Read the member roster, pending invitations, and API key inventory, and revoke a key.
• Reach any other REST API v1 operation through the catalog tools, including operations with no dedicated tool of their own. On a connection that selects toolsets, the catalog reaches only the toolsets you selected.
• Approve read-only or write access during browser sign-in.

Each tool declares whether it only reads data or also writes data. This lets a client ask for confirmation before a destructive call, on only the right tools. The following tools are flagged as destructive: delete_agent, delete_source, update_agent, update_source_metadata, revoke_api_key, improve_answer (it replaces the QnA pair written for the same message), test_agent (it spends credits), switch_organization (it changes the organization for every later call), and execute_delete_action (it runs a destructive operation from the catalog). Reads, creates, and restores are not destructive.

Organization scopingCopy Anchor Link

Tools operate on one active organization. You do not pass an organization ID with each call. get_current_organization reports the active organization. list_organizations marks it in the list. switch_organization changes it. The active organization is stored per user, and it does not depend on which organization you have open in the dashboard.

The active organization applies to every call automatically. For this reason, every response echoes the organization that it acted on:

{
  "organization": { "id": "org_...", "slug": "acme" },
  "items": [ ... ]
}

switch_organization echoes the organization that was active when you called it. The new scope applies starting with the next call.

Finding deleted recordsCopy Anchor Link

delete_agent and delete_source perform soft deletes. You have 30 days to restore a soft-deleted record. To find a record to restore, pass a status filter to the list tools:

Take the id from a status: "deleted" listing and pass it to restore_agent or restore_source. After restoreBefore passes, restore_agent fails with OUT_OF_GRACE_PERIOD. restore_source fails with INVALID_INPUT, or with NOT_FOUND after the cleanup job removes the record. restore_source also fails with LIMIT_EXCEEDED when the restored content would put the organization over its plan's training content limit. A website source is refused once that limit is already used up, because the size of its recrawl is not known in advance. Sources that belong to a soft-deleted agent are not listable. If you need to restore such a source, restore the agent first.

Reading back what you wroteCopy Anchor Link

get_agent takes an include array for larger fields: system_prompt, tools, sources, channels, and widget_config. widget_config returns every field that update_agent can write: the widget, lead-capture, floating-message, suggested-message, session-resume, and geo-restriction settings. You can read this field before you patch a value, or check it after you write a value.

Indexing is asynchronousCopy Anchor Link

create_source with type: "url" returns as soon as the crawl is queued. The response has status: "indexing" and a nextAction hint. The tool does not wait for the crawl to finish. On a large site, the crawl can take longer than the request timeout. Poll get_source with the returned sourceId until its status reads ready.

ErrorsCopy Anchor Link

A failure returns a JSON error object with a code, a message, and usually a suggestion:

{
  "organization": { "id": "org_...", "slug": "acme" },
  "error": {
    "code": "INVALID_INPUT",
    "message": "One of the supplied values is not in the format that field accepts.",
    "suggestion": "Check that every id argument is a uuid copied from a list or get response."
  }
}

The server rejects a malformed id or a malformed pagination cursor as INVALID_INPUT. It does not silently return the first page instead. On most lists, a cursor that is well formed, but whose anchor record is gone, is rejected as INVALID_CURSOR. Its suggestion tells you to omit the cursor and start from the first page. Contacts, voice calls and Help Center articles instead return an empty page with hasMore: false. An unexpected server-side failure returns INTERNAL_ERROR with a reference id. Quote this id to support. The server never forwards the underlying database error to the client.

TroubleshootingCopy Anchor Link

• Client says "not authenticated": Go to the MCP Server screen in your workspace dashboard. Check that your client is listed under Authorized Clients. If you run the install command again, the OAuth flow starts again.
• A stdio client cannot connect to streamable HTTP: Use the mcp-remote form shown above. It runs locally and sends requests to the AgentStack endpoint.
• Wrong organization: Call switch_organization. The organization field echoed on every response tells you which organization a call used. The MCP scope is stored per user. It does not follow the active organization in the dashboard.
• Sign-in succeeds, but every call is rejected: The client holds a token that was issued without an MCP scope. Remove the connector and add it again. This issues a new token, and the consent screen reappears, listing the scopes that you grant.
• Tool descriptions look out of date: The client caches the tool list from when it connected. Remove the connector and add it again to refresh the list.