MCP server for AI coding agents

What it does

The ImageTools backend doubles as an MCP server. Your agent can list your recent captures and pull them into the conversation as image content blocks — perfect right after a browser-extension selection capture, when you want the model to see what you're looking at instead of pasting files around.

• Streamable HTTP transport served by the existing backend at /mcp/ — nothing extra to install on the server, no extra port to open.
• stdio transport via a small Python package (mcp-server/) that calls the ImageTools REST API — useful for local dev or tunnelling.
• Bearer-token auth with tokens you mint and revoke yourself in the web UI.

Example prompts

• "Use my last 2 screenshots; the first shows the bug, the second shows the expected layout."
• "List my 3 most recent ImageTools screenshots."
• "Grab my latest screenshot and describe the UI regression you see in it."

Minting a token

1. Open Settings → MCP Access TokensIn the ImageTools web UI, as the user whose images the agent should read.
2. New TokenGive it a label that identifies the client, e.g. laptop claude-code, dev box.
3. Copy the imt_… token immediatelyIt is shown exactly once — only its sha256 hash is stored server-side (table mcp_authorizations).

Tokens are long-lived — there's no TTL — so treat them like passwords and revoke rather than rotate casually. Use one label per client so you can tell them apart in the list.

Streamable HTTP transport (deployed backend)

The MCP endpoint lives at {INSTANCE_URL}/mcp/ on your ImageTools backend — e.g. https://imagetools.example.com/mcp/ for a server at that address.

Add this entry to your Claude Code MCP config (~/.claude.json is the canonical location; or a project .mcp.json):

{
  "mcpServers": {
    "imagetools": {
      "type": "http",
      "url": "https://image-tools.a42r.com/mcp/",
      "headers": {
        "Authorization": "Bearer imt_YOUR_TOKEN_HERE"
      }
    }
  }
}

Or the equivalent README form with a plain url entry:

{
  "mcpServers": {
    "imagetools": {
      "url": "https://YOUR-INSTANCE/mcp/",
      "headers": { "Authorization": "Bearer imt_YOUR_TOKEN_HERE" }
    }
  }
}

Keep the token out of the config file by referencing an environment variable instead:

"headers": {
  "Authorization": "Bearer ${IMAGETOOLS_TOKEN}"
}

…and export IMAGETOOLS_TOKEN in the environment the agent starts in. MCP config is read at startup only — restart Claude Code after editing. Then verify by asking: "list my 3 most recent ImageTools screenshots."

stdio transport (local dev / tunnelling)

The stdio transport runs a small Python process on your machine (Python 3.11+) that calls the ImageTools REST API. Install the package from the repo:

pip install -e /path/to/ImageTools/mcp-server

Mint a token as above, then configure Claude Code:

{
  "mcpServers": {
    "imagetools": {
      "command": "python",
      "args": ["-m", "mcp_server.stdio"],
      "env": {
        "IMAGETOOLS_URL": "http://localhost:8082",
        "IMAGETOOLS_TOKEN": "imt_YOUR_TOKEN_HERE"
      }
    }
  }
}

Tools exposed

Counts are clamped server-side; oversized requests come back with a "clamped": true flag rather than an error.

Verifying a deployment

Two quick smoke tests with curl:

URL=https://imagetools.example.com
TOK=imt_...

# 1. token is valid → returns user_id
curl -sS -H "Authorization: Bearer $TOK" "$URL/api/v1/mcp-tokens/whoami"

# 2. MCP server responds → returns serverInfo + capabilities
curl -sS -X POST "$URL/mcp/" \
  -H "Authorization: Bearer $TOK" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"1"}}}'

Deployment notes

• The bearer token is the auth boundary for /mcp/ — when fronting the backend with an authenticating proxy (Authelia, basic auth), bypass the proxy auth for the /mcp path so agent calls work.
• Behind Traefik + Authelia, for example, /mcp has its own router without the auth middlewares, and the backend's internal-auth middleware already bypasses /mcp and /api/v1/mcp-tokens/.
• Source: mcp-server/ in the repo — README, stdio entrypoint and design docs under docs/superpowers/.