# Synergy MCP

A pay-per-call MCP server exposing the [Synergy](https://api.exo-trust.com) specialist
catalogue to MCP clients. Every specialist is an MCP tool; a tool call returns a
structured **x402 payment challenge** (HTTP 402) that the calling agent settles in
USDC from its own wallet before completing the call directly against the resource.

- **Hosted endpoint (streamable HTTP):** `https://api.exo-trust.com/mcp`
- **Catalogue + prices:** `GET https://api.exo-trust.com/discovery`
- **Protocol:** [x402](https://x402.org) · payments on Base (USDC, eip155:8453)

## Why

MCP hosts the users; x402 hosts the rail. This server bridges the two: agents that
speak MCP can discover and pay for specialist work per call without subscriptions,
accounts, or API keys — the payment is the authorization.

The server deliberately holds **no payment keys**. It never pays, never settles, and
never touches money: it returns the payment challenge so the *calling* agent settles
with its own wallet and facilitator.

## Tools

The tool registry is built live from `/discovery` (cached 300s), so new specialists
appear without a server restart. As of v0.1.0 the catalogue includes:

| Tool | What it does |
|---|---|
| `translate` | Translate text with source-language auto-detection |
| `summarize` | Structured summaries with key points |
| `classify` | Topic tags, category, sentiment with confidence |
| `code_explain` | Explain code: overview, flow, inputs/outputs, risks |
| `extract` | Structured field extraction from documents/invoices |
| `proofread` / `rewrite` | Grammar fixes / professional rewrites |
| `check_sanctions` | OFAC/consolidated sanctions list screen |
| `validate_vat` | EU VIES VAT-number validation |
| `lookup_lei` | GLEIF legal-entity lookup |
| `edgar_financials` | SEC EDGAR XBRL company fundamentals |
| `edgar_report` | Investment-grade fundamentals report (attested fetch + analysis) |
| `clinical_dd` | Clinical-stage due-diligence bundle (trial + FDA landscape) |
| `synergy_discovery` | List the live catalogue with prices and schemas |

All tools accept strict JSON input and return JSON only. Task payloads are treated as
untrusted data; deterministic tools (sanctions/VAT/LEI/EDGAR/clinical) never run
payloads through a shell, filesystem, or web tool.

## Using the hosted endpoint

Point any MCP client at `https://api.exo-trust.com/mcp` with the streamable HTTP
transport, then call a tool with a valid input payload. The response is a
`402 Payment Required` challenge:

```json
{
  "status": 402,
  "message": "Payment required",
  "payment": {
    "amount": "50000",
    "network": "eip155:8453",
    "asset": "USDC",
    "payTo": "0xC9e2A96d0C9D5B1e0656862dFEf849C95B8aFA4C"
  }
}
```

Settle the challenge with your x402 wallet/facilitator, then POST the same payload to
`https://api.exo-trust.com/execute/<task_type>` with the payment header to receive the
result. See the [x402 spec](https://x402.org) for the exact settlement flow.

## Self-hosting

The server is a single Python file (`mcp_server.py`) with no state and no keys:

```bash
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

.venv/bin/python mcp_server.py            # stdio transport
.venv/bin/python mcp_server.py --http     # streamable HTTP on :8123
SYNERGY_BASE_URL=https://api.exo-trust.com .venv/bin/python mcp_server.py --http
```

- `SYNERGY_BASE_URL` — gateway base URL (default `https://api.exo-trust.com`).
- `SYNERGY_MCP_PORT` — HTTP port (default `8123`).
- `SYNERGY_MCP_CATALOG_TTL` — catalogue cache TTL in seconds (default `300`).

When proxying the HTTP transport behind a public hostname, the SDK's DNS-rebinding
protection must be disabled for the public Host header (see `main()` in
`mcp_server.py`).

## License

MIT