MCP

The Model Context Protocol (MCP) is an open protocol that standardizes how AI applications provide context to LLMs. StackOne provides a pre-built MCP server for each linked account, giving your AI agents direct access to thousands of actions across hundreds of connectors. Use it from your product’s backend, from agent frameworks, or from the clients your users already run — ChatGPT, Claude, Cursor, and more.

Not sure if MCP is right for you? Check out Call Actions to understand when to use MCP vs the Agent SDK vs A2A.

MCP: Understanding the Protocol

What is MCP? The Model Context Protocol is an open standard originally developed by Anthropic and now adopted across the ecosystem — Claude, ChatGPT, Cursor, and most agent frameworks ship MCP clients. It defines how an AI application discovers and calls tools exposed by a server, regardless of which model or framework it uses.Why does MCP exist? Without a standard protocol, every app-to-tool connection is a custom integration. MCP solves this with a single, universal interface: any MCP client can use any MCP server’s tools with no integration code.How does it work? MCP uses familiar web standards: JSON-RPC 2.0 messages over an HTTP transport. A client initializes a session, calls tools/list to discover what the server offers (each tool has a name, description, and JSON Schema), and tools/call to run one. Servers can also expose prompts and resources, though tools are the part StackOne uses.MCP vs A2A: These protocols are complementary, not competing. MCP standardizes how agents connect to tools - stateless functions like calculators or database queries. A2A standardizes how agents communicate with other agents - autonomous systems that can reason, plan, and have multi-turn conversations. Use MCP when you need tools; use A2A when you need to collaborate with other agents.

How StackOne MCP works

The StackOne MCP Server dynamically generates its tool catalog based on your account’s configured connectors and enabled actions. Authentication to third-party providers is completely abstracted — you only need your StackOne API key and account ID. One linked account = one server endpoint; switch accounts by changing x-account-id.The server speaks the Streamable HTTP transport — HTTPS only, POST for all operations, no SSE, stateless. Behind the scenes, tool calls route through the same engine and actions as every other protocol StackOne offers.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.

Looking to use connectors inside an existing Agent Clients? See the Agent Setup walkthroughs (e.g. Claude Desktop, Claude Code) for ready-to-paste configs.

Calling actions

Before starting you need to have followed the previous setup steps described in the Getting Started. Then the full protocol round-trip with cURL:

Build your authentication headers

Every request goes to https://api.stackone.com/mcp with these headers:

Authorization: Basic <BASE64_ENCODED_STACKONE_API_KEY>
x-account-id: <ACCOUNT_ID>
Content-Type: application/json
Accept: application/json,text/event-stream

The Accept: application/json,text/event-stream header is mandatory — required by the MCP specification itself, on every request, with both formats listed. Without it you’ll receive 406 Not Acceptable. (MCP spec — Streamable HTTP transport)

To create the Basic auth token, append a colon to your API key, then base64 encode (see the API Keys guide if you need to generate a new key):

# -u auto-encodes to base64
curl -u "$STACKONE_API_KEY:" https://api.stackone.com/mcp ...

const encoded = Buffer.from(`${apiKey}:`).toString('base64');
fetch(url, { headers: { 'Authorization': `Basic ${encoded}` } });

import base64
encoded = base64.b64encode(f"{api_key}:".encode()).decode()
headers = {'Authorization': f'Basic {encoded}'}

Account IDs are on each linked account under Accounts, or via the List Accounts endpoint.For clients that can’t set custom headers, the account ID can fall back to a query parameter: https://api.stackone.com/mcp?x-account-id=<ACCOUNT_ID> (the header wins if both are present). The optional MCP-Protocol-Version header is handled automatically by most clients — StackOne supports the recent protocol revisions.

Initialize the connection

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": {}
    }
  }'

A successful response also confirms your authentication is configured correctly.

List available tools

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"
  }'

Call a tool

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 }
    }
  }'

Test it

AI Playground

No setup. Test with natural language instantly.

Postman

Fork the StackOne collection and test MCP requests.

MCP Inspector

Inspect the raw protocol exchange while debugging.

Tool discovery modes

See Tool Discovery for a full run-down between different tool discovery methods. The tool-mode query parameter controls how tools are registered — append ?tool-mode=search_execute to the endpoint URL to switch:

Mode	Tools registered	Best for
`individual` (default)	One tool per action	Small action sets (under ~50 tools), or when the agent should see every tool upfront
`search_execute`	2 tools: search + execute	Large catalogs, context window constraints

In search_execute mode the server registers exactly two tools:

Tool	Description
`{provider}_search_actions`	Takes a natural language `query` (optional `top_k` — default 10, max 50) and returns ranked matching actions with their `action_id` and similarity score
`{provider}_execute_action`	Executes any action by its `action_id`, with optional `path`, `query`, `body`, and `headers`

The agent must call search_actions first — action_id values are discovered at runtime based on what’s enabled for the account. Never hardcode them.

Per-user connections

Every end-user of your product maps to a linked account — your backend holds the API key, and each user’s tools are addressed by their account ID. Two ways to wire MCP into your product:

Server-side — your backend calls the MCP endpoint with your API key and the end-user’s x-account-id. The key never leaves your infrastructure; switching users is just switching the header.
Token URLs — for user-facing clients that connect directly, hand out a token URL (https://api.stackone.com/mcp?token=<session_token>) generated in the dashboard: open the connector and click Use in Agent. Your API key stays on the backend.

Your end-users can also bring their own MCP clients: give them a token URL and point them at the per-client walkthroughs in Agent Setup — ChatGPT, Claude, Cursor, and more.

Calling actions

Test it

AI Playground

Postman

MCP Inspector

Tool discovery modes

Per-user connections

Framework guides

Anthropic SDK

OpenAI Agents SDK

Vercel AI SDK

LangChain

LangGraph

CrewAI

Pydantic AI

Google ADK

Azure AI Foundry

​Calling actions

​Test it

AI Playground

Postman

MCP Inspector

​Tool discovery modes

​Per-user connections

​Framework guides

Anthropic SDK

OpenAI Agents SDK

Vercel AI SDK

LangChain

LangGraph

CrewAI

Pydantic AI

Google ADK

Azure AI Foundry

Calling actions

Test it

Tool discovery modes

Per-user connections

Framework guides