​

MCP (Model Context Protocol)

Use the MCP server when your client speaks the Model Context Protocol (for example AI tooling that connects to tools over stdio) instead of calling the REST API directly. The MCP layer is a thin bridge: it validates tool input and forwards requests to the same FinalSay Agent API as HTTP. Payloads and outcomes match the Agent API. The adapter advertises three tools in tools/list: request_human_approval and create_approval (identical create semantics; choose the name that fits your prompt) plus get_approval_result for polling. Tool metadata includes per-field descriptions and limits in the JSON Schema so MCP clients can surface them to models. Runtime validation matches POST /v1/approvals except timeout is not accepted over MCP — expiry policy always uses the agent’s dashboard defaults on the server. Use the REST Agent API directly if you need per-request timeout overrides. There is no separate “MCP secret”—you use the same Agent ID and workspace API key as in API keys & automations.

​

Tools

​

request_human_approval

Creates an approval request for an agent. Required inputs

• question
• context_markdown
• options

Optional inputs

• request_id (omit to let the API assign a UUID; returned in the tool response JSON)
• correlation_id
• notification_summary
• Callback configuration (url, optional headers)

Field shapes and limits match POST /v1/approvals in the Agent API for the fields exposed here (timeout is REST-only). When agent callback authentication is enabled in the web dashboard, the integration API still adds that header to outbound callbacks at delivery time. Do not pass the auth secret through MCP tool parameters—there is no tool field for it by design.

​

create_approval

Same request body, validation, and POST /v1/approvals behavior as request_human_approval. Use whichever name fits your prompt: this one is described for fire-and-forget creates where the client does not wait—your workflow supplies the pause (for example n8n Wait + callback.url such as $execution.resumeUrl, or a later step that calls get_approval_result).

​

get_approval_result

Returns the current result for a request. Required inputs

• request_id

The response is either still pending or the same final payload you would get from GET /v1/approvals/:requestId/result.

​

Authentication

Your MCP client must send HTTP headers on the MCP transport (as your product’s MCP host allows):

• x-agent-id: <your agent UUID>
• x-api-key: <your workspace API key>

The adapter forwards these headers to the API and does not store or create credentials.

​

n8n and Docker (Streamable HTTP)

When n8n runs in Docker and the MCP adapter runs on your host (e.g. npm run dev:mcp), n8n must call the host using a URL the container can resolve—commonly http://host.docker.internal:<port>/mcp (with or without a trailing slash). fetch failed almost always means the TCP connection never reached the adapter (not an MCP protocol error). Checklist:

1. Adapter listens on all interfaces — use MCP_HTTP_HOST=0.0.0.0 (the repo dev:http script sets this). If the process binds only to 127.0.0.1, containers cannot connect via host.docker.internal.
2. Port — must match the running server (default 4009 for npm run dev:mcp).
3. Linux Docker — host.docker.internal is not defined by default. Add to the n8n service, for example:
   extra_hosts: ["host.docker.internal:host-gateway"]
   (or use your host LAN IP instead of host.docker.internal).
4. Smoke test from the n8n container — curl -sS http://host.docker.internal:4009/ should return JSON with "ok": true. If this fails, fix networking before debugging MCP.
5. Hosted n8n (n8n Cloud) cannot reach host.docker.internal on your laptop—use a public HTTPS URL or run n8n locally.

The adapter process must also reach INTEGRATION_API_BASE_URL (usually http://localhost:4000 when both run on the host). If you ever run the adapter inside Docker too, point that variable at the integration API using a Docker-reachable hostname (for example http://host.docker.internal:4000). If you combine MCP Client Tool with community nodes as AI tools, n8n also needs N8N_COMMUNITY_PACKAGES_ALLOW_TOOL_USAGE=true — see n8n: AI Agent tools.

​

Environment

Your deployment configures where the adapter sends traffic: If you self-host infrastructure, your operator supplies this value when running the MCP adapter.

​

Errors

• Validation errors — Reported before any network call to the API.
• Non-2xx API responses — Surfaced as MCP tool errors. Examples mapped from the Agent API include 409 idempotency_conflict, 429 rate_limited, and 403 USAGE_APPROVAL_LIMIT when the team is over an approval quota (billing/plan limits when enabled).
• Unknown tool names — MCP error with isError: true.

​

Other ways to integrate

• Custom HTTP — curl and generic clients
• n8n — Community nodes package n8n-nodes-finalsay, HTTP Request, and webhooks
• Zapier — Custom request / webhooks
• Agent API — Direct REST reference
• Automation limits & billing