Client Setup

Client Setup

How to register reportmate-mcp with an MCP client. Every example uses the same shape, because the server supports exactly one transport.

Transport

__main__.main() calls mcp.run() with no arguments, which is FastMCP's stdio transport. The client launches the process and speaks MCP over its stdin and stdout. There is no HTTP or SSE listener in this repo, no port to bind, and no URL to point a client at — a client that only supports remote servers cannot use this one as shipped.

That also means every instance is single-tenant: the credentials in the process environment are the credentials every tool call uses.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\) and add an entry under mcpServers. This assumes the reportmate-mcp console script is on your PATH — see Getting Started for installing it with uv tool install.

{
  "mcpServers": {
    "reportmate": {
      "command": "reportmate-mcp",
      "env": {
        "REPORTMATE_API_URL": "https://reportmate.example.com",
        "REPORTMATE_API_KEY": "rm_yourclient_yoursecret"
      }
    }
  }
}

Restart Claude Desktop. The eight tools appear under the server name reportmate.

To run it from a working copy instead of an installed package, point the command at uv:

{
  "mcpServers": {
    "reportmate": {
      "command": "uv",
      "args": ["--directory", "/path/to/reportmate-mcp", "run", "reportmate-mcp"],
      "env": {
        "REPORTMATE_API_URL": "https://reportmate.example.com",
        "REPORTMATE_API_KEY": "rm_yourclient_yoursecret"
      }
    }
  }
}

Claude Code

Add it with claude mcp add. Everything after -- is the command Claude Code will launch.

claude mcp add reportmate \
  -e REPORTMATE_API_URL=https://reportmate.example.com \
  -e REPORTMATE_API_KEY=rm_yourclient_yoursecret \
  -- reportmate-mcp

Confirm it registered and started:

claude mcp list

To share the server with everyone working in a repo, add -s project so the definition is written to .mcp.json — put the key in the environment rather than in the committed file if you do.

Container

The published image runs the same stdio entry point, so the client launches docker and the container's stdio is the transport. -i is required; -t must not be used.

{
  "mcpServers": {
    "reportmate": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "REPORTMATE_API_URL",
        "-e", "REPORTMATE_API_KEY",
        "ghcr.io/reportmate/reportmate-mcp"
      ],
      "env": {
        "REPORTMATE_API_URL": "https://reportmate.example.com",
        "REPORTMATE_API_KEY": "rm_yourclient_yoursecret"
      }
    }
  }
}

Generic MCP client

Any client that can launch a stdio server needs three things: the command, an empty argument list, and the two environment variables.

Field	Value
Transport	stdio
Command	reportmate-mcp
Arguments	none
Environment	REPORTMATE_API_URL, and REPORTMATE_API_KEY or REPORTMATE_PASSPHRASE

Verify

Ask the agent to call api_health, then fleet_summary.

api_health is the cheapest tool and tells you whether the URL is right and the API can reach its database — but its endpoint is unauthenticated upstream, so it passes even with a bad credential. fleet_summary is the cheapest tool that actually proves the credential. If both succeed, the server, the URL, and the key are all correct.