Integrating flAPI with Claude

Anthropic's Claude clients (Claude Desktop, Claude Code, the Anthropic SDK) speak the Model Context Protocol natively. flAPI exposes its tools, resources, and prompts over the JSON-RPC 2.0 HTTP transport at POST /mcp/jsonrpc, so any MCP-aware Claude client can connect to it once a thin transport bridge is in place.

This page covers the practical setup for the three most common Claude entry points.

How flAPI's MCP Endpoint Works

• One transport URL: POST http://<host>:<port>/mcp/jsonrpc
• Optional session header echoed back by the server: Mcp-Session-Id
• One liveness URL: GET /mcp/health (not part of MCP itself)
• Authentication (when enabled) via Authorization: Bearer <token> or Authorization: Basic ...

If you have not already configured an mcp-tool: block on an endpoint, start with the MCP Overview.

1. Claude Desktop

Claude Desktop's mcpServers configuration launches each MCP server as a stdio subprocess. Because flAPI speaks HTTP, you need a stdio→HTTP bridge. The recommended bridge is mcp-remote (works for any HTTP-transport MCP server).

Step 1 — Locate your config file

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Step 2 — Add the flAPI bridge

{
  "mcpServers": {
    "flapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/mcp/jsonrpc"
      ]
    }
  }
}

If your flAPI server requires a Bearer token, pass an Authorization header through the bridge:

{
  "mcpServers": {
    "flapi": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8080/mcp/jsonrpc",
        "--header",
        "Authorization: Bearer ${FLAPI_TOKEN}"
      ],
      "env": {
        "FLAPI_TOKEN": "your-bearer-token"
      }
    }
  }
}

Step 3 — Restart Claude Desktop

Quit Claude Desktop fully and reopen it. Your flAPI tools will appear in the "Tools" indicator and Claude can call them in conversation.

What about "command": "curl"? Earlier examples in some places on the internet suggest using curl as the command. That does not work: Claude Desktop expects a long-lived stdio MCP process speaking JSON-RPC line frames, not a one-shot HTTP request. Use mcp-remote (or any equivalent stdio↔HTTP bridge such as mcp-proxy) until Claude Desktop ships native HTTP-transport support.

2. Claude Code (CLI)

Claude Code supports MCP servers via the same mcpServers config block. The setup is identical to Claude Desktop—register the bridge and Claude Code will list flAPI tools alongside its built-ins:

{
  "mcpServers": {
    "flapi": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8080/mcp/jsonrpc"]
    }
  }
}

If you are using flAPI's Config Service (flapi --config-service), Claude Code can also drive the flapi_* admin tools to create, update, or reload endpoints during a coding session. See the MCP Config Tools page for the full tool catalog.

3. Direct API Use (Anthropic SDK)

When you call Claude via the Anthropic API, you typically expose tools through the Tool Use feature rather than through MCP transport. The easiest pattern is:

1. Call flAPI's tools/list once at startup and translate each MCP tool definition into an Anthropic tool definition (the JSON Schema inputSchema maps directly to the Anthropic input_schema field).
2. When Claude returns a tool_use block, call flAPI's tools/call with name and arguments.
3. Feed the resulting content array back to Claude as a tool_result.

A minimal Python skeleton:

import requests
import anthropic

FLAPI = "http://localhost:8080/mcp/jsonrpc"
client = anthropic.Anthropic()

def jsonrpc(method, params=None, _id=1):
    r = requests.post(FLAPI, json={
        "jsonrpc": "2.0",
        "id": _id,
        "method": method,
        "params": params or {},
    })
    return r.json()["result"]

# 1) Initialise once
jsonrpc("initialize", {
    "protocolVersion": "2025-11-25",
    "clientInfo": {"name": "py-claude-bridge", "version": "1.0.0"},
})

# 2) Pull tools and translate
mcp_tools = jsonrpc("tools/list")["tools"]
anthropic_tools = [
    {
        "name": t["name"],
        "description": t["description"],
        "input_schema": t["inputSchema"],
    }
    for t in mcp_tools
]

# 3) Ask Claude
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=anthropic_tools,
    messages=[{"role": "user", "content": "Top US campaigns by revenue?"}],
)

# 4) If Claude requests a tool, dispatch back to flAPI
for block in response.content:
    if block.type == "tool_use":
        result = jsonrpc("tools/call", {
            "name": block.name,
            "arguments": block.input,
        })
        # result["content"] is an array of content blocks ready
        # to send back to Claude as a tool_result

This pattern works for any MCP server—the inputSchema→input_schema mapping is intentional in the MCP spec.

Example Conversation

Once Claude is wired up, you can chat naturally:

You: "What are our top-performing marketing campaigns in the US?"

Claude: Let me check that.
[Tool call: get_campaign_performance { "country": "US" }]

Claude: Based on the data, here are your top US campaigns this quarter:
  1. Summer Sale 2024  — $45K revenue, 150K clicks (0.30 RPC)
  2. Back to School    — $38K revenue, 120K clicks (0.32 RPC)
  3. Mid-Year Refresh  — $31K revenue, 110K clicks (0.28 RPC)

Claude sees the full inputSchema you defined in YAML, so it knows which parameters are required, what shape they take, and what each one means. The richer your description: fields, the better its tool selection.

Troubleshooting

Symptom	Likely cause	Fix
No tools appear in Claude	Bridge cannot reach flAPI	Run curl http://localhost:8080/mcp/health
Tools listed but every call fails	Auth required by flAPI	Add --header "Authorization: Bearer ..." to mcp-remote
Method not found (-32601)	Method name typo or wrong protocol	Confirm method is one of initialize, tools/list, tools/call, resources/list, resources/read, prompts/list, prompts/get, ping, logging/setLevel, completion/complete
Authentication required (-32001)	flAPI's MCP auth is enabled and no/invalid token sent	Verify token; for per-method auth see the Protocol Reference
Stale tools after editing YAML	Endpoint not reloaded	Restart flAPI, or use flapi_reload_endpoint when running --config-service

More Information

• MCP Overview — concepts, configuration, security model
• MCP Protocol Reference — every JSON-RPC method, error code, and session header
• MCP Config Tools — admin tools for managing flAPI from Claude
• YAML Syntax — full mcp-tool / mcp-resource / mcp-prompt schema
• Authentication — securing the MCP transport

Need help wiring Claude into your data stack? Contact our team.