Skip to content
BlockNext

Using the MCP server

Every integration node in BlockNext doubles as an MCP tool. The stack ships a dedicated MCP service (mcp-api, port 3100): point Claude — or any MCP client — at it and use your connected services directly from chat, with the same credentials you set up in BlockNext.

How it’s organized

Section titled “How it’s organized”

mcp-api exposes one MCP server per provider, each serving that provider’s nodes as tools over the streamable HTTP transport:

GET  http://localhost:3100/servers          # public catalog of available servers
POST http://localhost:3100/{serverId}/mcp   # the MCP endpoint for one provider

Connect to the slack server and the client sees the Slack nodes as callable tools; same for google_docs, notion, and every other provider — the MCP server reference lists every server and endpoint, and the node reference doubles as the tool catalog. Endpoints are stateless, so any client that speaks streamable HTTP works.

Tools are generated from the same descriptor that powers the node form and validation, so names, input/output schemas, and behavior hints (read-only, destructive, idempotent) are always in sync with the platform — there is no separate tool catalog to maintain. Tool names are node IDs (e.g. slack_send_message); outputs come back both as structured content ({items: [...]} matching the node’s output schema) and as JSON text blocks.

Authentication

Section titled “Authentication”

Access is gated by API keys (bnx_-prefixed, stored server-side only as a hash). Create one in BlockNext with the mcp:invoke scope and send it as the X-API-Key header on every request. A typical client configuration:

{
  "mcpServers": {
    "blocknext-slack": {
      "type": "http",
      "url": "https://mcp.blocknext.ai/slack/mcp",
      "headers": { "X-API-Key": "bnx_..." }
    }
  }
}

The key must be an organization key — MCP tools run against an organization’s credentials and credits, so a call arriving with any other owner is refused.

Credentials are references, never secrets

Section titled “Credentials are references, never secrets”

Tools that talk to an external service take an extra required credentials parameter — but it carries opaque references (credential:organization:<uuid> — the UI key) to connections already stored on the platform, never secret material. On every call the server:

  1. verifies the reference belongs to the calling organization — a key can never replay another organization’s references;
  2. resolves and decrypts the credential server-side, refreshing OAuth tokens transparently if needed;
  3. runs the node’s executor with the standard contract.

The credential security model applies unchanged: nothing an MCP client sends or receives ever contains a secret.

One call at a time, and a record of every one

Section titled “One call at a time, and a record of every one”

An MCP client can fire tool calls as fast as it likes, so the server puts two limits in front of them.

Concurrency is per organization. Every call takes a slot before it runs and releases it afterwards; when the slots are full the next call waits rather than piling on. Workflow runs draw from the same pool, so an assistant hammering tools cannot starve your scheduled flows. Slot count comes from SEMAPHORE_MAX_CONCURRENT_EXECUTIONS when self-hosting, and from your plan on Cloud.

Every call is bounded. MCP_MAX_EXECUTION_TIME (5 minutes by default) caps how long a single tool may run — a hung provider fails that one call instead of holding a slot forever. The clock starts once the call has a slot, so time spent queueing is not charged against it.

Every finished call is recorded. Each invocation is written to your organization’s history with the tool, the API key that made it, the parameters, the credential references (never the secrets), the outputs and any error. Find it under Organization → History → Tools (alongside workflow runs), where the list updates live as calls come in. This is your audit trail: what an assistant did on your behalf, when, and with which key.

Why this matters

Section titled “Why this matters”

The long-term direction of BlockNext is chat-first automation: instead of only composing flows on a canvas, you compose capability from a conversation. The MCP server is that bridge — everything you connect to BlockNext becomes available to every MCP-capable assistant you use.