> Existing subscriptions only. These x-api-key / Workbench / MCP instructions do not authenticate the new prepaid budget. New customers: use [the prepaid HTTP guide](../prepaid-api.html) and [prepaid kit](xynthera-ai-integration-kit.zip). No autonomous payment or recharge is provided.

# Xynthera Workbench MCP adapter

Version 0.1.0-beta. JSON-only, stateless Streamable HTTP on one endpoint. Deployment and real-client acceptance are separate release checks. `index.ts` is a Deno Edge entrypoint; `handler.mjs` is portable and dependency-free. No server credential is embedded or provisioned by this adapter.

## Actual protocol profile

Supported fixed protocol versions: `2025-11-25`, `2025-06-18`, `2025-03-26`. Initialize negotiates one of those versions; this is not a claim to support future/latest versions. Clients initialize first, send `notifications/initialized`, then include their negotiated `MCP-Protocol-Version` header. Missing version uses the backward-compatible 2025-03-26 profile. No sessions, SSE, server callbacks, tasks, prompts, batching or arbitrary network tools. GET/DELETE return 405; notifications accepted return **202 with no body**, as required by the documented transport. OPTIONS is 204.

Implemented: `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, initialized/cancelled notifications. The catalogue resource is `xynthera://catalog`. Unknown tools/methods have JSON-RPC errors; validation errors in Workbench appear as `isError:true` tool results. There are no outstanding server-originated requests to accept response messages for.

Origin is checked: absent Origin is supported for server clients; the public Xynthera site is the only permitted browser Origin by default. Invalid Origin gets 403. No wildcard authenticated CORS. The deployment does not require or announce OAuth discovery: **custom `x-api-key` header authentication** must be supported by the client. This profile is not a complete OAuth MCP authorization implementation and may not connect to clients requiring OAuth-only login.

## Tools and authorization

| Tool | Key | Exact upstream |
|---|---|---|
| `get_catalog` | Public | None |
| `get_purchase_link` | Public | None; existing guest checkout URL only |
| `check_contract` | Caller HTTP header | `/v1/contracts/check` |
| `check_events` | Caller HTTP header | `/v1/events/check` |
| `reconcile_invoice` | Caller HTTP header | `/v1/invoices/reconcile` |

All upstream routes are hard-coded to this project's Workbench origin. Redirects fail. Tool arguments cannot select URLs, headers or credentials. The caller key is forwarded only to those paths; authentication, tenant isolation, permissions, quota and idempotence are enforced by the deployed Workbench. Checks consume the existing allowance shared by contract/event/invoice checks and five Agent Action control operations. They are not marked read-only because quota/report storage changes state. `request_id` is mandatory; an exact retry reuses the downstream receipt according to Workbench policy.

Request limit 64 KiB including JSON-RPC envelope, depth 40, 10,000 nodes. A near-limit underlying request therefore needs a slightly smaller payload through MCP. Upstream response reads are bounded at 192 KiB; fetch/body total has a 20-second abort timeout. No console logging. Credential fields in arguments are rejected; credential-looking fields and the literal caller key are stripped/redacted in the returned upstream payload. Reports can still contain user-supplied business data; callers choose what to submit.

No automatic payment, checkout creation, bank/ERP verification, wallet integration or Agent Action execution. The catalogue says **81 billing countries**, separately from national integrations. Previously accepted subscription allowances and terms apply; no automatic overages; report retention seven days. Catalogue changes must update this snapshot and its tests alongside the authoritative commercial configuration.

## Curl / client configuration

Published endpoint: https://pfxxzsnboehxsefyajml.supabase.co/functions/v1/xynthera-ai-mcp. A protocol handshake and authenticated invoice check were verified; acceptance by every third-party client is not claimed. The first two calls need no key.

```sh
curl "$XYNTHERA_MCP_URL" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
curl "$XYNTHERA_MCP_URL" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl "$XYNTHERA_MCP_URL" -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_catalog","arguments":{}}}'
```

Client-neutral configuration example (translate `headersFromEnvironment` to the real client's secure-header configuration; it is not a standardized MCP config key):

```json
{
  "name": "xynthera-workbench",
  "transport": "streamable-http",
  "url": "https://pfxxzsnboehxsefyajml.supabase.co/functions/v1/xynthera-ai-mcp",
  "headersFromEnvironment": {"x-api-key": "XYNTHERA_API_KEY"}
}
```

Store your key in the client's secret configuration. Never paste it into tool arguments, model prompts or committed JSON. Paid call arguments example:

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"check_events","arguments":{"input":{"request_id":"mcp-example-1","events":[]}}}}
```

The HTTP request separately supplies the key header; use the real Workbench fixtures for meaningful domain inputs. This adapter does not introduce a second validation schema or change business semantics.

## Verify

`node --test mcp/test/handler.test.mjs` from the project root. Tests cover negotiation, notifications, Origin, transport/header rejection, body bound, public discovery/no payment, exact route forwarding, missing key, credential injection, downstream errors/redaction/bounds and timeout. Release additionally requires public initialize/list/read and one authorized real-fixture call to each deployed underlying endpoint. No real-client integration is claimed from unit tests alone.

Primary specification consulted 13 October 2026:

- https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
- https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle
- https://modelcontextprotocol.io/specification/2025-11-25/server/tools