> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# StackOne MCPs

> Connect all StackOne platform actions directly to LLM clients and agents via the Model Context Protocol

The **[Model Context Protocol (MCP)](https://modelcontextprotocol.io)** is an open protocol that standardizes how AI applications provide context to LLMs.

StackOne provides **production-ready MCP servers** for each linked account, giving your AI agents direct access to 10,000+ actions across hundreds of integrations. See the complete list at [stackone.com/integrations](https://www.stackone.com/integrations).

<Tip>
  **Not sure if MCP is right for you?** Check out our [Agent Protocols Guide](/guides/calling-stackone-actions) to understand when to use MCP vs AI Toolset (SDK) vs A2A.
</Tip>

***

## MCP Server Endpoint

```
https://api.stackone.com/mcp
```

**Required headers:**

* `Authorization: Basic <base64-encoded-api-key>`
* `x-account-id: <account-id>` (or `?x-account-id=` query param)

Authentication to third-party providers is completely abstracted - you only need your StackOne API key and account ID. Accounts must be linked beforehand through the [StackOne Hub](/guides/embedding-stackone-hub) or via [auth links](/guides/auth-link).

***

## Fastest Way to Test

<CardGroup cols={3}>
  <Card title="AI Playground" icon="play" href="https://app.stackone.com/playground">
    No setup. Test with natural language instantly
  </Card>

  <Card title="Postman" icon="https://mintcdn.com/stackone-60/ukzqjoO9pVfH9ilh/images/mcp/logos/postman.svg?fit=max&auto=format&n=ukzqjoO9pVfH9ilh&q=85&s=b5d9867a85829951d3e50f703021c8a8" href="/mcp/app-guides/postman" width="800" height="800" data-path="images/mcp/logos/postman.svg">
    Fork the StackOne collection and test MCP requests
  </Card>

  <Card title="MCP Inspector" icon="magnifying-glass">
    Run `npx @modelcontextprotocol/inspector https://api.stackone.com/mcp`
  </Card>
</CardGroup>

***

## How It Works

```mermaid theme={null}
flowchart LR
    Client[LLM Client or Agent] <-->|MCP Streamable HTTP| StackOneMCP[StackOne MCP Server]
    StackOneMCP <-->|tools/list| Toolset[StackOne Tool Catalog]
    StackOneMCP <-->|tools/call| Providers[(Connected SaaS APIs)]
    IntegrationConfig[Integration & Account Settings] -->|Defines available tools| Toolset

    style StackOneMCP fill:#10b981,stroke:#059669,color:#fff
    style Toolset fill:#10b981,stroke:#059669,color:#fff
    style IntegrationConfig fill:#10b981,stroke:#059669,color:#fff
```

The StackOne MCP Server dynamically generates its tool catalog based on your account's configured integrations and enabled actions.

<AccordionGroup>
  <Accordion title="Multiple Integration Options" icon="plug">
    Use the MCP server, the [Actions RPC endpoint](/platform/api-reference/actions/make-an-rpc-call-to-an-action), the [Unified API endpoints](/hris/introduction), or [A2A Agents](/a2a/introduction), all using the same linked account. You can also access the [StackOne AI Toolset](/agents/typescript/introduction) for specialized LLM tools.
  </Accordion>

  <Accordion title="Accuracy & Context Engineering" icon="brain">
    Enhance your agent's toolset with [Tool Search](/agents/typescript/tool-search) for natural language discovery of relevant tools. Every tool has structured input/output schemas and documentation.
  </Accordion>

  <Accordion title="Customizable & Extensible" icon="gear">
    Toggle tools on or off, customize your toolset, or create your own connectors using StackOne's Connector Engine and AI Builder.
  </Accordion>

  <Accordion title="Purposeful Action Design" icon="bullseye">
    StackOne tools aren't direct wrappers to single API endpoints. Many are mapped to high-value, context-optimized actions tailored to common business use cases.
  </Accordion>
</AccordionGroup>

***

## Framework Guides

Most frameworks support MCP natively:

<CardGroup cols={3}>
  <Card title="Claude SDK" icon="message" href="/mcp/framework-guides/anthropic-sdk" />

  <Card title="Vercel AI SDK" icon="triangle" href="/mcp/framework-guides/vercel-ai-sdk" />

  <Card title="OpenAI Agents" icon="brain" href="/mcp/framework-guides/openai-agents-sdk" />

  <Card title="Pydantic AI" icon="python" href="/mcp/framework-guides/pydantic-ai" />

  <Card title="CrewAI" icon="users" href="/mcp/framework-guides/crewai" />

  <Card title="Google ADK" icon="google" href="/mcp/framework-guides/google-adk" />
</CardGroup>

***

## App Guides

<CardGroup cols={4}>
  <Card title="Claude Desktop" icon="https://mintcdn.com/stackone-60/WsmKpuoeBZmio9QO/images/mcp/logos/claude.svg?fit=max&auto=format&n=WsmKpuoeBZmio9QO&q=85&s=404b448b2b3013a55ecf71943aec656f" href="/mcp/app-guides/claude-desktop" width="1200" height="1200" data-path="images/mcp/logos/claude.svg" />

  <Card title="Goose" icon="https://mintcdn.com/stackone-60/3C44zDmMwMrJMHXV/images/mcp/logos/goose.png?fit=max&auto=format&n=3C44zDmMwMrJMHXV&q=85&s=09f6d6d96f9aae06c5841d23908946a8" href="/mcp/app-guides/goose" width="1024" height="1024" data-path="images/mcp/logos/goose.png" />

  <Card title="n8n" icon="https://mintcdn.com/stackone-60/3C44zDmMwMrJMHXV/images/mcp/logos/n8n.png?fit=max&auto=format&n=3C44zDmMwMrJMHXV&q=85&s=9364b633ee3073731b7a7b3d569a2b8a" href="/mcp/app-guides/n8n" width="1024" height="1024" data-path="images/mcp/logos/n8n.png" />

  <Card title="Postman" icon="https://mintcdn.com/stackone-60/ukzqjoO9pVfH9ilh/images/mcp/logos/postman.svg?fit=max&auto=format&n=ukzqjoO9pVfH9ilh&q=85&s=b5d9867a85829951d3e50f703021c8a8" href="/mcp/app-guides/postman" width="800" height="800" data-path="images/mcp/logos/postman.svg" />
</CardGroup>

***

## Manual Testing (cURL)

<AccordionGroup>
  <Accordion title="Initialize connection">
    ```bash theme={null}
    curl -X POST https://api.stackone.com/mcp \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' \
      -d '{
        "jsonrpc": "2.0",
        "id": "init-1",
        "method": "initialize",
        "params": {
          "clientInfo": { "name": "my-client", "version": "1.0.0" },
          "protocolVersion": "2025-06-18",
          "capabilities": {}
        }
      }'
    ```
  </Accordion>

  <Accordion title="List available tools">
    ```bash theme={null}
    curl -X POST https://api.stackone.com/mcp \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' \
      -d '{
        "jsonrpc": "2.0",
        "id": "tools-1",
        "method": "tools/list"
      }'
    ```
  </Accordion>

  <Accordion title="Call a tool">
    ```bash theme={null}
    curl -X POST https://api.stackone.com/mcp \
      -H 'Authorization: Basic <BASE64_APIKEY_COLON>' \
      -H 'x-account-id: <ACCOUNT_ID>' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json, text/event-stream' \
      -d '{
        "jsonrpc": "2.0",
        "id": "call-1",
        "method": "tools/call",
        "params": {
          "name": "bamboohr_list_employees",
          "arguments": { "limit": 10 }
        }
      }'
    ```
  </Accordion>
</AccordionGroup>

***

## Tool Modes

The MCP endpoint supports a `tool-mode` query parameter that controls how tools are registered.

| Mode                   | Tools registered          | When to use                                |
| ---------------------- | ------------------------- | ------------------------------------------ |
| `individual` (default) | One tool per action       | Small action sets, full tool visibility    |
| `search_execute`       | 2 tools: search + execute | Large catalogs, context window constraints |

**Search & execute mode** is useful when an integration exposes many actions. Instead of registering hundreds of individual tools, the server exposes just two:

* `{provider}_search_actions` — search for actions by natural language query
* `{provider}_execute_action` — execute an action by its `action_id`

The agent calls `search_actions` first to discover available action IDs, then calls `execute_action` to run the chosen action.

Enable it by appending `?tool-mode=search_execute` to the MCP URL:

```
https://api.stackone.com/mcp?tool-mode=search_execute
```

See [Tool Modes](/mcp/tool-modes) for full details, parameter reference, and setup examples for Claude Desktop and Claude Code.

***

## Key Features

* **Account Specific**: Each linked account gets its own MCP server endpoint
* **Streamable HTTP Transport**: Uses modern HTTP-based MCP transport (not SSE)
* **Complete Platform Access**: All StackOne actions available as MCP tools
* **Action Selection Control**: Only enabled actions from your integration config are returned
* **Production Ready**: Authentication, rate limiting, and security built-in

***

## Troubleshooting

| Error            | Solution                                                                   |
| ---------------- | -------------------------------------------------------------------------- |
| `401/403`        | Check API key encoding and that `x-account-id` belongs to the same project |
| `405`            | Ensure you're using POST and `Content-Type: application/json`              |
| Empty tools list | Verify account is active and actions are enabled in integration config     |

For more, see [Troubleshooting Guide](/mcp/troubleshooting) and [Authentication & Security](/mcp/auth-security).