MCP server

AgentStack exposes a Streamable HTTP MCP endpoint at https://www.agentstack.build/api/mcp. It uses OAuth bearer authorization and does not rely on server-sent events. A missing, invalid, expired, or disabled-client token produces a JSON-RPC 401 response with a WWW-Authenticate resource-metadata challenge. Clients must complete the advertised authorization flow. Do not substitute a REST API key. The other direction works: the REST API at /api/v1 also accepts the same OAuth access token (see REST API authentication).

The endpoint has three forms. /api/mcp mounts every toolset plus the catalog tools. /api/mcp/x/<toolsets> takes a comma-separated toolset list in the path, for a client that can only accept a pasted URL. /api/mcp/readonly mounts only the operations that read data. A client that can send a custom header can also select toolsets on /api/mcp with X-MCP-Toolsets. The path form never reads that header, so the path always wins when both are present.

A toolset name is the operation's own domain. These toolsets mount dedicated tools: activity, agents, analytics, apikeys, catalog, contacts, conversations, inbox, members, organizations, sources, and webhooks. These toolsets have no dedicated tools and are reachable only through the catalog: actions, auditlogs, billing, channels, conversation notes, customdomains, customroles, domains, helpcenter, helppage, ingest, messages, notion, topics, and voice. Percent-encode conversation notes in the path form, or select it with the header. The catalog tools mount under every selection, because they are how a client discovers the operations that are in scope. The selection still gates them: execute_read_action, execute_write_action, and execute_delete_action refuse an operation outside the selected toolsets with the error code OUT_OF_TOOLSET_PARTITION. search_api_actions does not filter on the selection, so a search result is a hint and not a guarantee. Partitioning is server-side: an unselected tool is never mounted, so a narrow connection keeps the client's tool list small. /api/mcp/readonly is enforced the same way. It drops execute_write_action and execute_delete_action while keeping search, details, and execute_read_action, so a read-only connection keeps full discovery and cannot act. Neither form replaces scopes. A token still needs the scope for each tool it calls.

The dashboard's MCP Server screen is the place to copy a client configuration. It also shows authorized clients and recent MCP calls. The dashboard route under Dashboard shows the same MCP Server screen. This guide applies to both routes. Each row in Authorized Clients has a Revoke button. Revoking a client removes its access at once, and the client must be authorized again before it can connect. If credentials or requested access change, revoke the client or reconfigure it locally. Then reconnect or re-authorize.

Use MCP for an interactive developer client that needs delegated access to AgentStack. Use REST API keys for unattended services. The next guides cover scopes, tools, and client-specific setup patterns.