MCP Integration

Connect Claude and other LLMs to the Zanzibar Digital Free Zone API

What is MCP?

The Model Context Protocol (MCP) allows AI assistants like Claude to interact with external systems. The Zanzibar Digital Free Zone backend exposes all CRUD operations and business logic as MCP tools.

Endpoint: POST https://app.zdfz.live/mcp

Authentication

Every request to https://app.zdfz.live/mcp must carry a Bearer token in the Authorization header:

Authorization: Bearer fz_u_...
Use an MCP-scoped Personal API Key

The key must have mcp_scope set. An API-only Personal API Key from your Profile panel will not work here, and the MCP endpoint will return:

{"jsonrpc":"2.0","error":{"code":-32000,"message":"API key does not have MCP access"},"id":1}
Mint your MCP key
  1. Sign in to https://app.zdfz.live.
  2. Open Profile → Personal API Keys.
  3. Choose API + MCP read for viewing tools, or API + MCP read+write for external agents that may perform writes.
  4. Enter your password. If two-factor authentication is enabled, read+write minting also requires a current authenticator code.
  5. Copy the fz_u_... token shown once. Treat it as a password.

The token is minted via apikeyservice.generate_personal; any personal key whose row carries mcp_scope can authenticate to /mcp. The built-in AI assistant keeps its own read-only key.

Test your key with one curl (no mcp-remote bridge)

The Claude Desktop / Claude Code snippets below use the npx mcp-remote bridge, which can hide auth errors behind setup noise. Verify your key first with a direct initialize call:

curl -X POST https://app.zdfz.live/mcp \
  -H "Authorization: Bearer fz_u_..." \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}},"id":1}'

A 200 response with a result.serverInfo block confirms the key is good and the bridge layer is the only thing left to configure.

For a full end-to-end walkthrough (curl, Python, Claude Code, troubleshooting), see Programmatic Access.

Claude Desktop

Add this to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "freezone": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.zdfz.live/mcp"
      ]
    }
  }
}
Claude Code

Add an MCP server in your project's .mcp.json:

{
  "mcpServers": {
    "freezone": {
      "command": "npx",
      "args": ["mcp-remote", "https://app.zdfz.live/mcp"]
    }
  }
}
Related