mcp_config_examples.md

# Connecting the CrossBeam MCP server

The server (`mcp_server.py`) exposes six tools: `list_municipalities`,
`list_review_tracks`, `list_knowledge`, `review_plan_set`,
`analyze_corrections_letter`, `generate_checklist`.

LLM-backed tools need a provider + API key: pass `api_key` per call, or set the
provider's env var (`ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` /
`GROQ_API_KEY`) on the server and pass just `provider`.

## Claude Desktop / local STDIO clients
`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "crossbeam": {
      "command": "python",
      "args": ["/absolute/path/to/mcp_server.py"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}
```

## HTTP / SSE (HF Space, n8n, Gemini, tunnels)
Run the server in HTTP mode:
```bash
MCP_HTTP=1 MCP_PORT=7860 python mcp_server.py
```
- **HF Space**: use the Dockerfile.mcp below; the endpoint is
  `https://<user>-<space>.hf.space/mcp`.
- **n8n**: MCP Client node → Server URL `http://<host>:7860/mcp` (or the HF URL).
- **Tunnel (ngrok/Cloudflare)**: `ngrok http 7860` → use the public URL + `/mcp`.
- **Local remote clients**: point them at `http://localhost:7860/mcp`.

## ChatGPT / Gemini
Use their MCP/custom-connector settings with the HTTP endpoint above. If a client
can't reach `localhost`, expose the server with a tunnel and use that URL.

## Passing files
`review_plan_set` and `analyze_corrections_letter` take the PDF as **base64**
(`pdf_base64` / `letter_base64`). Most agent clients base64-encode an attached file
automatically; for manual calls, `base64 -w0 plan.pdf`.


## Deploying on Hugging Face Spaces — IMPORTANT

HF Spaces only reads a file named exactly **`Dockerfile`**. A `Dockerfile.mcp`
sitting in the repo is ignored, so the Space keeps serving whatever the real
`Dockerfile` says. Symptom when the Space is running the Streamlit UI but a client
points at `/mcp`:

```
HTTP transport failed: Error POSTing to endpoint: Method Not Allowed;
SSE fallback failed: Invalid content type, expected "text/event-stream"
```
That is Streamlit answering an MCP request — not an MCP bug.

Pick one layout:

| Goal | Use this as `Dockerfile` | Endpoint |
|---|---|---|
| UI **and** MCP in one Space (default) | `Dockerfile` (runs `combined_server.py`) | `https://<user>-<space>.hf.space/mcp` |
| MCP only | rename `Dockerfile.mcp` → `Dockerfile` | `https://<user>-<space>.hf.space/mcp` |
| UI only | rename `Dockerfile.ui-only` → `Dockerfile` | n/a |

For the Space `razaali10/Land-Develop-MCP`, the default `Dockerfile` now serves both,
so the connector URL is:

```
https://razaali10-land-develop-mcp.hf.space/mcp
```

Both `/mcp` and `/mcp/` are accepted.