Using the MCP server

Every integration node in BlockNext doubles as an MCP tool, and the platform itself is an MCP server too. The stack ships a dedicated MCP service (mcp-api, port 3100): point Claude — or any MCP client — at it and use your connected services, workflows and triggers directly from chat.

How it’s organized

mcp-api exposes one MCP server per provider, each serving that provider’s nodes as tools, plus the platform server, whose tools read and manage your own account. All of them speak 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 server
POST http://localhost:3100/platform/mcp     # the platform server

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, endpoint and scope, and the node reference doubles as the tool catalog. Endpoints are stateless, so any client that speaks streamable HTTP works.

Provider 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

There are two ways in. OAuth works with every server and is what MCP clients with authorization support (Claude, Cursor, VS Code, LM Studio, …) use on their own; API keys are for provider servers only, and for clients or scripts that cannot run a browser flow.

OAuth (recommended)

mcp-api is also an OAuth 2.1 authorization server (RFC 8414 discovery, dynamic client registration, PKCE, resource indicators). Point a client at a server URL with no headers at all: the client discovers the authorization server, opens BlockNext in your browser, you pick the organization the connection should act on and approve the requested scopes, and the client receives a short-lived access token bound to that one server plus a refresh token. Nothing to copy, nothing to store.

Cloud
Self-hosted

{
  "mcpServers": {
    "blocknext-slack": { "type": "http", "url": "https://mcp.blocknext.ai/slack/mcp" },
    "blocknext-platform": { "type": "http", "url": "https://mcp.blocknext.ai/platform/mcp" }
  }
}

{
  "mcpServers": {
    "blocknext-slack": { "type": "http", "url": "http://localhost:3100/slack/mcp" },
    "blocknext-platform": { "type": "http", "url": "http://localhost:3100/platform/mcp" }
  }
}

localhost:3100 is the default from MCP_API_BASE_URL; behind a reverse proxy use whatever hostname you publish mcp-api on. The exact URL for each server is shown in the app, built from MCP_SERVER_URL_TEMPLATE. The consent screen lives in the web UI, so MCP_OAUTH_ISSUER_URL, MCP_OAUTH_RESOURCE_URL and MCP_OAUTH_CONSENT_URL_TEMPLATE must be the public URLs — see configuration.

Scopes are per server: provider servers ask for mcp:invoke; the platform server asks for platform:read and platform:write. A token issued for one server is rejected by every other one.

API keys

Provider servers also accept an API key (bnx_-prefixed, stored server-side only as a hash) with the mcp:invoke scope, sent as the X-API-Key header on every request:

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

The key must be an organization key — provider tools run against an organization’s credentials, so a call arriving with any other owner is refused. The platform server does not accept API keys: its tools act as you, so they need a token you approved.

The platform server

platform is BlockNext itself as an MCP server. Its tools never return secrets and always act on the organization you approved the connection for:

Tool	Scope	What it does
`platform_get_me`	`platform:read`	The signed-in user, the active organization and every organization you belong to.
`platform_list_workflows`, `platform_get_workflow`	`platform:read`	Your workflows, and one workflow with the nodes on its canvas.
`platform_list_triggers`	`platform:read`	Schedule and webhook triggers.
`platform_set_trigger_active`	`platform:write`	Turn a trigger on or off.
`platform_list_executions`	`platform:read`	Workflow runs, newest first.
`platform_list_tool_invocations`	`platform:read`	Tool calls made through the MCP servers, newest first.
`platform_list_credentials`	`platform:read`	Connected credentials — names and types only.

On Cloud the server also exposes platform_get_credit_balance. Ask an assistant “which of my triggers are off?” or “pause the nightly report” and it can answer from here.

Credentials are references, never secrets

Provider 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:

verifies the reference belongs to the calling organization — a token or key can never replay another organization’s references;
checks the reference is a credential of the type the tool expects;
resolves and decrypts the credential server-side, refreshing OAuth tokens transparently if needed;
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

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

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 — provider tools (source mcp) and platform tools (source platform) alike. Each invocation is written to your organization’s history with the tool, the API key that made it (when one was used), 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 through which connection.

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 servers are that bridge — everything you connect to BlockNext, and BlockNext itself, becomes available to every MCP-capable assistant you use.