drillsite-mcp

A production-ready Model Context Protocol (MCP) server in Python, built on the official MCP Python SDK. It lets an AI agent (Claude Desktop, Claude Code, or any MCP client) query a drill-site prospectivity API through validated tools, resources and a prompt.

The sample backend is a small FastAPI service that scores mining exploration zones, modelled on the prospectivity platform I run at Metalgenomic. The data here is synthetic.

MCP client (Claude, Inspector)
        │  stdio  |  SSE  |  streamable HTTP
        ▼
drillsite-mcp  (MCPServer: tools · resources · prompt)
        │  httpx, API key, timeouts, safe error mapping
        ▼
Drill-site Prospectivity API  (FastAPI + Pydantic)

FastMCP → MCPServer. In SDK v2 the FastMCP class was renamed MCPServer (from mcp.server.mcpserver import MCPServer). The decorator API is the same. To run this on SDK v1, use from mcp.server.fastmcp import FastMCP and pin mcp<2.

What it exposes

Related MCP server: Earth Grounding MCP

Production concerns handled

• Input validation before any request leaves the server. Zone ids must match Z-000, scores are bounded 0–1, top_n 1–20, notes ≤ 500 characters. Invalid input is rejected by the SDK's Pydantic validation and never reaches the API.

• One shared HTTP client created in the server lifespan and closed on shutdown, with connect/read timeouts and the API key sent as a header.

• Safe error mapping. Timeouts, 401/403, 404, 422 and 5xx become short ToolError messages. Status codes, URLs and keys are logged to stderr, never returned to the model.

• Prompt-injection mitigation. Text written by people (field notes) comes back under untrusted_field_notes, with control characters stripped and length capped. The server instructions and the drill_plan prompt tell the agent to treat it as data.

• Tool annotations (readOnlyHint, destructiveHint, …) so clients can decide which calls need user confirmation.

• stdout is reserved for the protocol under stdio; logs go to stderr.

• End-to-end tests run MCP client → server → httpx → FastAPI in one process.

Quick start

Requires Python 3.11+.

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                               # 10 tests, all in-process

Run the API (terminal 1):

export DRILLSITE_API_KEY=dev-key     # Windows PowerShell: $env:DRILLSITE_API_KEY="dev-key"
drillsite-api                        # http://127.0.0.1:8000  (docs at /docs)

Run the MCP server (terminal 2), on either transport:

drillsite-mcp --transport stdio                    # for Claude Desktop / Claude Code
drillsite-mcp --transport sse --port 8001          # SSE at http://127.0.0.1:8001/sse
drillsite-mcp --transport streamable-http --port 8001   # http://127.0.0.1:8001/mcp

Configuration (environment variables):

Connect from Claude Desktop or Claude Code (stdio)

{
  "mcpServers": {
    "drillsite": {
      "command": "/absolute/path/to/.venv/bin/drillsite-mcp",
      "args": ["--transport", "stdio"],
      "env": { "DRILLSITE_API_KEY": "dev-key" }
    }
  }
}

Claude Code: claude mcp add drillsite -- /absolute/path/to/.venv/bin/drillsite-mcp --transport stdio

Debugging with the MCP Inspector

The MCP Inspector is the official tool for exercising an MCP server by hand. It needs Node.js. Keep the API running.

1. UI mode over stdio. The Inspector launches the server for you:

npx @modelcontextprotocol/inspector -e DRILLSITE_API_KEY=dev-key drillsite-mcp --transport stdio

Open the URL it prints. Click Connect, then:

• Tools → List Tools: you should see the four tools with their JSON schemas.

• Run rank_zones with top_n = 2 → Z-001, Z-004.

• Run get_zone with zone_id = ../admin → a validation error. The request never reached the API (check terminal 1: no log line).

• Resources: read zones://all, then the template zones://{zone_id} with Z-003.

• Prompts: get drill_plan.

2. UI mode over SSE. Start the server with --transport sse --port 8001, then in the Inspector choose transport SSE and URL http://127.0.0.1:8001/sse.

3. CLI mode (scriptable, good for CI smoke tests):

npx @modelcontextprotocol/inspector --cli drillsite-mcp --transport stdio --method tools/list
npx @modelcontextprotocol/inspector --cli drillsite-mcp --transport stdio \
  --method tools/call --tool-name rank_zones --tool-arg top_n=2
npx @modelcontextprotocol/inspector --cli drillsite-mcp --transport stdio \
  --method resources/read --uri zones://Z-001

Common problems

Set LOG_LEVEL=DEBUG to see every backend call in stderr.

Docker

docker build -t drillsite-mcp .
docker run --rm -p 8001:8001 -e DRILLSITE_API_URL=http://host.docker.internal:8000 drillsite-mcp

The image runs the server over SSE on port 8001 as a non-root user.

Project layout

src/drillsite_mcp/api.py      sample FastAPI backend
src/drillsite_mcp/server.py   MCP server: tools, resources, prompt, transports
tests/test_server.py          end-to-end tests through a real MCP client

License

MIT