# The CONVERG3NCE MCP server

CONVERG3NCE exposes its audit engine to AI clients as a remote
[Model Context Protocol](https://modelcontextprotocol.io) server, so an agent can query
a brand's agent-readiness the same way it queries anything else.

## Endpoint

```
POST https://api.converg3nce.com/mcp
```

| Property | Value |
|---|---|
| Transport | **Streamable HTTP** |
| Server name | `converg3nce` |
| Server version | `0.1.0` |
| Session handling | **Stateless** — no `Mcp-Session-Id`, no session continuity |
| Max request body | 5 MB |
| Max request duration | 300 s |

There is no SSE-only endpoint and no stdio server. Every request constructs a fresh
server instance, so nothing is carried between calls — each tool call must stand alone.

## Authentication

All ten tools are key-gated. Pass a bearer token:

```http
Authorization: Bearer <your-api-key>
```

Keys are compared by SHA-256 digest using a constant-time comparison. Raw tokens are
never logged; audit rows record only a truncated hash of the key that made the call.

!!!warning There is no self-serve key issuance
Keys are provisioned by CONVERG3NCE. Contact us for one. Adoption is a key plus one
config line — but the key comes from a person, not a signup form.
!!!

### Auth failures

| Status | JSON-RPC code | Meaning |
|---|---|---|
| `401` | `-32001` | Missing or invalid bearer key |
| `503` | `-32002` | Server misconfigured — authentication is not configured |

The `503` is deliberate. On a deployed environment, an unset key variable causes the
server to **refuse all requests** rather than fall open. An unauthenticated endpoint
that spends money per call is itself the abuse vector.

## Client configuration

+++ Claude Code
```bash
claude mcp add --transport http converg3nce https://api.converg3nce.com/mcp \
  --header "Authorization: Bearer <your-api-key>"
```
+++ claude_desktop_config.json
```json
{
  "mcpServers": {
    "converg3nce": {
      "type": "http",
      "url": "https://api.converg3nce.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}
```
+++ Raw JSON-RPC
```bash
curl -sS https://api.converg3nce.com/mcp \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
The response is `text/event-stream`, so a client that cannot read SSE framing will not
be able to parse it even though the request succeeded.
+++

## The ten tools

| Tool | Tier | What it does |
|---|---|---|
| [`run_audit`](tools/run-audit.md) | mutate | Starts a full audit run |
| [`get_audit_status`](tools/get-audit-status.md) | read | Polls a run's status |
| [`get_report`](tools/get-report.md) | read | Fetches the rendered markdown report |
| [`get_score_history`](tools/get-score-history.md) | read | Score over time for a brand |
| [`list_fixes`](tools/list-fixes.md) | read | Prioritized fixes for a brand |
| [`generate_fix_artifacts`](tools/generate-fix-artifacts.md) | mutate | JSON-LD and `llms.txt` templates for a fix |
| [`compare_brands`](tools/compare-brands.md) | read | Category leaderboard |
| [`verify_merchant`](tools/verify-merchant.md) | read | Should an agent transact with this merchant |
| [`publish_report`](tools/publish-report.md) | mutate | Publishes a branded client report |
| [`list_published_reports`](tools/list-published-reports.md) | read | Previously published report links |

## A typical session

```
run_audit(domain, brand_name, category)   ──▶ { run_id, status: "pending" }
        │
        │  poll, ~2–4 minutes
        ▼
get_audit_status(run_id)                  ──▶ { status: "complete" }
        │
        ▼
get_report(run_id)                        ──▶ { markdown }
list_fixes(brand)                         ──▶ [ ranked fixes ]
generate_fix_artifacts(fix_id)            ──▶ { jsonld, llms_txt }
```

## Also see

[!ref Target=_self text="Rate limits"](rate-limits.md)
[!ref Target=_self text="Error codes"](errors.md)