Apideck MCP Server

Apideck MCP 服务

用于 Apideck Unified API 的模型上下文协议服务。通过一次集成，将任何兼容 MCP 的 Agent 连接到 200 多个连接器，包括会计系统、HRIS 平台、CRM、文件存储等。

快速连接

{
  "mcpServers": {
    "apideck": {
      "command": "npx",
      "args": ["-y", "@apideck/mcp", "start"],
      "env": {
        "APIDECK_API_KEY": "YOUR_API_KEY",
        "APIDECK_CONSUMER_ID": "YOUR_CONSUMER_ID",
        "APIDECK_APP_ID": "YOUR_APP_ID"
      }
    }
  }
}

export APIDECK_API_KEY="..."
export APIDECK_CONSUMER_ID="..."
export APIDECK_APP_ID="..."

claude mcp add --transport http apideck https://mcp.apideck.dev/mcp \
  --header "Authorization: Bearer $APIDECK_API_KEY" \
  --header "x-apideck-consumer-id: $APIDECK_CONSUMER_ID" \
  --header "x-apideck-app-id: $APIDECK_APP_ID"

claude mcp add apideck \
  -e APIDECK_API_KEY="$APIDECK_API_KEY" \
  -e APIDECK_CONSUMER_ID="$APIDECK_CONSUMER_ID" \
  -e APIDECK_APP_ID="$APIDECK_APP_ID" \
  -- npx -y @apideck/mcp start

{
  "mcpServers": {
    "apideck": {
      "url": "https://mcp.apideck.dev/mcp",
      "headers": {
        "x-apideck-api-key": "YOUR_API_KEY",
        "x-apideck-consumer-id": "YOUR_CONSUMER_ID",
        "x-apideck-app-id": "YOUR_APP_ID"
      }
    }
  }
}

{
  "mcpServers": {
    "apideck": {
      "url": "https://mcp.apideck.dev/mcp",
      "headers": {
        "x-apideck-api-key": "YOUR_API_KEY",
        "x-apideck-consumer-id": "YOUR_CONSUMER_ID",
        "x-apideck-app-id": "YOUR_APP_ID"
      }
    }
  }
}

Claude Desktop（.mcpb 插件 bundle）

Apideck 提供 Claude 插件 bundle（.mcpb — Anthropic 的模型上下文协议 Bundle 格式）。将它放入 Claude Desktop，即可使用完整服务（330 个端点工具 + 4 个工作流工具），并通过标准插件界面输入 API 密钥 / consumer ID / app ID。

pnpm mcpb:build       # → dist/mcp-server.mcpb (~590 KB)

该 bundle 在本地构建；CI 发布到 GitHub Releases 的工作暂缓进行。使用 Claude Desktop 的插件安装程序打开 .mcpb；Claude Desktop 会读取 manifest.json，配置凭据并启动服务。

工具

330 个工具，涵盖 10 个统一 API：

工作流工具

按意图分组的工作流会通过单个 MCP 工具编排多个调用，避免 Agent 反复往返调用，以及经常出错的字段传递。

托管服务

服务已在以下地址上线：

https://mcp.apideck.dev/mcp

通过请求头传递凭据：

Vault 会话令牌（JWT）

若要让终端用户的浏览器或 Agent 无需你的 API 密钥即可调用工具，请在后端创建一个 Vault 会话，并传递其 session_token：

Authorization: Bearer <session_token>
x-apideck-auth-type: JWT
x-apideck-app-id: <your app ID>
x-apideck-consumer-id: <the session's consumer ID>

服务会在每次 Apideck API 调用中转发 x-apideck-auth-type: JWT，其方式与 API Explorer 对会话进行身份验证相同。其他任何值都会继续使用 API 密钥进行身份验证。以下是一些限制：

• 只有在请求中同时提供 bearer 令牌时，该请求头才会生效。服务自身的 APIDECK_API_KEY 绝不会作为 JWT 发送。
• 会话令牌无法创建新的 Vault 会话。如果连接需要重新授权，工具会返回普通错误消息，而不会提供重新授权链接。
• JWT 身份验证仅适用于 HTTP。stdio CLI 始终使用 API 密钥。

使用方范围限定（可选）

连接时无需提供使用方 ID。可以不设置 APIDECK_CONSUMER_ID / x-apideck-consumer-id，以不限定范围的方式启动服务，然后在调用任意工具时传入 consumer_id 参数，为每次调用提供或覆盖使用方：

execute_tool({ name: "crm-contacts-all", input: { consumer_id: "acme-inc" } })

优先级：每次调用的 consumer_id 参数优先于 APIDECK_CONSUMER_ID 环境变量 / x-apideck-consumer-id 请求头。

• 不限定范围的调用适用于不需要使用方的应用范围端点，例如 Webhook 日志（webhook-event-logs-all）和 vault-connections-all。
• 使用方范围限定的端点若在未提供使用方时调用，会返回 Apideck 的“需要使用方”错误，因此请为这些端点设置 consumer_id（或环境变量 / 请求头）。

锁定身份（可选启用）

若要将身份固定为启动时请求头 / 环境变量中的值，并阻止 Agent 在每次调用时切换使用方或连接，请使用 --lock-identity（CLI），或在托管服务 URL 后添加 ?lock_identity=true。锁定后，每次调用中的 consumer_id / service_id 参数都会被忽略。默认关闭。需要 consumer_id 作为路径参数的 Vault 使用方工具（例如 vault-consumers-one）只接受已锁定的使用方；任何其他值，或未锁定使用方时，都会被拒绝。service_id 路径参数（例如 vault-connections-one）不受影响。

三种模式

Dynamic 模式

Agent 逐步发现工具 — 与预先加载全部 330 个工具架构相比，token 数减少约 85%：

list_tools({})
  → { total: 330, domains: [{ name: "accounting", count: 143 }, ...],
      hint: "Call list_tools(domain=X) or list_tools(search_terms=[...])" }

list_tools({"search_terms": ["invoices"]})
  → accounting-invoices-all, accounting-invoices-add, accounting-invoices-one, ...

describe_tool_input({"name": "accounting-invoices-all"})
  → Full JSON Schema with all parameters

execute_tool({"name": "accounting-invoices-all", "input": {"limit": 10}})
  → Invoice data from the connected accounting system

直接在 input 中放入操作字段，并遵循 describe_tool_input 返回的契约。动态执行会在分发前验证参数；格式错误的封装和违反架构的输入会返回 isError: true，并包含 code: "invalid_tool_input"、字段路径或问题路径，且不会进行下游调用。 写入工具也会拒绝未知的顶层字段，因此未声明的内容不会传递到 API。验证错误不会回显提交的值。仍支持按调用覆盖 consumer_id 和 service_id；身份锁定规则仍然适用。 请求架构会省略只读响应字段，同时保留可写的关联 ID 和必需的路径 ID。这不会增加幂等性，也不会让写入重试变得安全。

你可以将 dynamic 模式与范围筛选器结合使用：

{
  "mcpServers": {
    "apideck": {
      "command": "node",
      "args": ["dist/bin/mcp.js", "--mode", "dynamic", "--scope", "read"],
      "env": { "APIDECK_API_KEY": "...", "APIDECK_CONSUMER_ID": "...", "APIDECK_APP_ID": "..." }
    }
  }
}

Code 模式

Code 模式只暴露两个工具，而非 330 多个。它专为更喜欢将端点作为方法调用，而不是发起工具调用的 Agent 设计：

1. apideck_search — 按子字符串查找端点，并返回 camelCase 方法名
2. apideck_run — 执行 JS 脚本，其中 apideck.<methodName> 绑定到实时端点分发器，并在 node:vm 中进行沙箱隔离

apideck_search("invoices")
  → {
      count: 4,
      endpoints: [
        { name: "accounting-invoices-list",   method: "accountingInvoicesList" },
        { name: "accounting-invoices-create",  method: "accountingInvoicesCreate" },
        { name: "accounting-invoices-get",     method: "accountingInvoicesGet" },
        { name: "accounting-invoices-delete",  method: "accountingInvoicesDelete" }
      ]
    }

apideck_run({
  script: "return await apideck.accountingInvoicesList({ request: { limit: 5 } })"
})
  → Invoice data from the connected accounting system

沙箱会移除 process、require、fs、child_process 和其他 Node 全局对象 — 脚本只能访问 apideck 对象。

范围

按 HTTP 方法类别筛选工具：

重复使用该标志即可组合多个范围（--scope read --scope write）。在托管端点上，使用逗号分隔的查询参数：?scopes=read,write。无效或空值会被拒绝（CLI 解析错误 / HTTP 400）。所有模式均适用范围筛选，包括 code。

连接任意 Agent 框架

远程（托管 — 无需本地安装）

# OpenAI Agents SDK
from agents import Agent
from agents.mcp import MCPServerHTTP

agent = Agent(
    name="Apideck Agent",
    mcp_servers=[MCPServerHTTP(
        url="https://mcp.apideck.dev/mcp",
        headers={
            "x-apideck-api-key": "...",
            "x-apideck-consumer-id": "...",
            "x-apideck-app-id": "..."
        }
    )]
)

# Pydantic AI
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerHTTP

agent = Agent("anthropic:claude-sonnet-4-5", mcp_servers=[
    MCPServerHTTP(
        url="https://mcp.apideck.dev/mcp",
        headers={
            "x-apideck-api-key": "...",
            "x-apideck-consumer-id": "...",
            "x-apideck-app-id": "..."
        }
    )
])

# LangChain / LangGraph
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "apideck": {
        "url": "https://mcp.apideck.dev/mcp",
        "transport": "streamable_http",
        "headers": {
            "x-apideck-api-key": "...",
            "x-apideck-consumer-id": "...",
            "x-apideck-app-id": "..."
        }
    }
})
tools = await client.get_tools()

本地 stdio（用于开发）

pnpm install
pnpm build

# Dynamic mode (default)
APIDECK_API_KEY=... APIDECK_CONSUMER_ID=... APIDECK_APP_ID=... node dist/bin/mcp.js start

# Static mode (all 330 tools)
APIDECK_API_KEY=... node dist/bin/mcp.js start --mode static

# Code mode
APIDECK_API_KEY=... node dist/bin/mcp.js start --mode code

# Read-only
APIDECK_API_KEY=... node dist/bin/mcp.js start --scope read

# OpenAI Agents SDK (local stdio)
from agents import Agent
from agents.mcp import MCPServerStdio

mcp = MCPServerStdio(name="apideck", params={
    "command": "node",
    "args": ["dist/bin/mcp.js", "start", "--mode", "dynamic"],
    "env": {
        "APIDECK_API_KEY": "...",
        "APIDECK_CONSUMER_ID": "...",
        "APIDECK_APP_ID": "..."
    }
})
agent = Agent(name="Apideck Agent", mcp_servers=[mcp])

可靠性

运行时会自动重试失败的请求，避免暂时性错误传递给 Agent：

• 重试的状态码：408、500、502、503、504
• 重试的网络错误：ECONNRESET、ECONNREFUSED、ETIMEDOUT 等
• 策略：指数退避，最多 4 次尝试，最长间隔为 30 s
• 幂等性：仅对 GET、HEAD、PUT、DELETE、OPTIONS、TRACE 触发重试 — 不会自动重试 POST/PATCH

二进制内容

返回图像或音频的 File Storage 端点会将其作为原生 MCP 内容块发送，而不是作为 JSON 中的 base64 字符串：

{ "type": "image", "data": "<base64>", "mimeType": "image/png" }
{ "type": "audio", "data": "<base64>", "mimeType": "audio/mpeg" }

支持多模态 MCP 内容的 Agent（Claude、GPT-4o）会接收原始字节 — 无需额外的解码步骤。

许可证

MIT