MCP

The Formance MCP server exposes selected Formance capabilities to MCP-compatible clients such as coding assistants and local agent runtimes. It lets an agent inspect financial data and validate Numscript without giving it write access to the stack.

Enable MCP on a stack#

Check your local fctl version before enabling MCP:

fctl version

Enable the MCP module on the target stack with fctl:

fctl stack module enable mcp

Run this command from an authenticated fctl context that targets the organization and stack where MCP should be enabled.

Run MCP over stdio#

MCP clients typically start the server as a local process and communicate with it over standard input and output. With Formance, fctl can serve as the MCP process:

fctl stack mcp serve --transport=stdio --organization=YOUR_ORGANIZATION_ID --stack=YOUR_STACK_ID

Your MCP client configuration should pass the target organization and stack to fctl. The exact configuration format depends on the client:

{
  "mcpServers": {
    "formance": {
      "command": "fctl",
      "args": [
        "--organization=YOUR_ORGANIZATION_ID",
        "--stack=YOUR_STACK_ID",
        "stack",
        "mcp",
        "serve",
        "--transport=stdio"
      ]
    }
  }
}

Replace the --organization and --stack values with your own environment.

Verify the server responds#

A stdio MCP server has no interactive output: run it on its own and it appears to hang while it waits for JSON-RPC on standard input. That is expected — it is not a failure.

To confirm the server is healthy without an MCP client, pipe an initialize request into it:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | fctl stack mcp serve --transport=stdio --organization=YOUR_ORGANIZATION_ID --stack=YOUR_STACK_ID

A healthy server replies with a single JSON line advertising its capabilities:

{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"logging":{},"tools":{"listChanged":true}},"protocolVersion":"2024-11-05","serverInfo":{"name":"stack-mcp","version":"v0.1.0"}}}

If you see an organization not specified or stack not specified error instead, add the flags shown above. If the command hangs with no reply, check that the mcp module is enabled on the stack and that your fctl context is authenticated.

Available capabilities#

The MCP server is read-only for Formance data. It is intended for exploration, diagnostics, and assisted development workflows.

Typical workflow#

1. Enable the mcp module on a Stack v3.2 or later stack.
2. Configure your MCP client to start fctl stack mcp serve --transport=stdio.
3. Ask the client to inspect Ledger, Payments, or Reconciliation state.
4. Use Numscript validation before promoting a script into an operational workflow.