apideck-mcp

Apideck MCP

The Apideck MCP server exposes the Unified API as Model Context Protocol tools. One MCP server, 330+ tools, 200+ SaaS connectors.

If you're building an agent that needs to read/write SaaS data — invoices, candidates, employees, files, tickets, customers — and your agent runtime supports MCP (Claude Code, Claude Desktop, Cursor, Windsurf, OpenAI Agents SDK, Pydantic AI, LangChain), this is usually the right choice over a language SDK.

When to prefer MCP over the language SDK

Use the MCP server when…	Use a language SDK (apideck-node, apideck-python, …) when…
You're building an agent (LLM-driven control flow)	You're building a deterministic backend integration
You want dynamic tool discovery — agent picks tools at runtime	You know at compile time which methods you'll call
Your runtime already speaks MCP (Claude Code, Cursor, OpenAI Agents SDK, …)	You're embedding Apideck inside a non-agent service
You want Vault OAuth elicitation handled for free (consent URLs surface as MCP elicitations)	You'll wire OAuth flows yourself
Tool descriptions matter for agent decision-making	Your code knows which method to call regardless of description quality

Endpoints

Hosted:    https://mcp.apideck.dev/mcp
Stdio:     npx -y @apideck/mcp
Source:    https://github.com/apideck-libraries/mcp

Pass credentials via headers (HTTP)

x-apideck-api-key:      <your Apideck API key>
x-apideck-app-id:       <your application ID>
x-apideck-consumer-id:  <end-user / customer ID>

Pass credentials via env vars (stdio)

APIDECK_API_KEY=...  APIDECK_APP_ID=...  APIDECK_CONSUMER_ID=...  npx -y @apideck/mcp

IMPORTANT RULES

• PREFER dynamic mode (?mode=dynamic or --dynamic, the default). It exposes 4 meta-tools — list_tools, describe_tool_input, execute_tool, list_scopes — instead of 330 individual tools, dropping initial token cost from ~25-40K to ~1,300. Switch to static mode only for small fixed tool sets.
• CALL list_tools first with relevant search_terms (["accounting", "invoices"], ["hris", "employees"]). Don't enumerate 330 tools.
• PREFER workflow tools over manual chains — see "Intent-grouped workflows" below. The agent that picks apideck-pay-bill instead of stitching accounting-bills-get + accounting-bill-payments-create will succeed more often and leak less context.
• HANDLE URL elicitations: when an upstream call hits a missing/expired Vault connection, the server throws UrlElicitationRequiredError (MCP error code -32042) carrying a one-time consent URL. Surface this URL to the user, wait for them to complete OAuth, then retry the original tool call.
• USE x-apideck-service-id when a consumer has multiple connections of the same unified API — e.g. the consumer connected both Xero and QuickBooks, and the user wants the call to target Xero. Without this, Apideck routes to whichever connection is first.
• USE scopes to restrict an agent to a subset of capabilities — ?scopes=read for analysis agents, ?scopes=read,write to allow non-destructive changes, omit for full access. Scopes are enforced server-side, so a "read-only" agent literally cannot call destructive tools no matter what the prompt says.