# MCP connection

- Endpoint: `https://sunglassesguides.com/mcp` (Streamable HTTP, **stateless**: no session id; every POST is independent)
- Server: `sunglassesguides` 1.0.0, a small stateless JSON-RPC implementation (no sessions, JSON responses, no SSE stream), tested against the official MCP TypeScript SDK client
- Protocol versions negotiated: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05` (latest supported: `2025-11-25`). The newer stateless revision `2026-07-28` (server/discover) is **not** supported yet.
- Methods: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`, `ping`. No resources or prompts.
- Tools: `get_sunglasses_coverage`, `resolve_sunglasses`, `find_sunglasses`, `compare_sunglasses`, `get_sunglasses_variant`, `get_sunglasses_offers`. All have `readOnlyHint: true`, `destructiveHint: false`, `openWorldHint: false`, plus `inputSchema` and `outputSchema`.
- Results: `structuredContent` is the same JSON envelope as the REST API; a text block carries the same JSON. Business outcomes such as NO_MATCH_IN_COVERED_CATALOG or NO_OFFER_COVERAGE are normal results (`isError:false`). Invalid arguments, unknown ids and DATA_VERSION_CHANGED are tool errors (`isError:true`) with the error envelope. Protocol problems (bad JSON-RPC, unknown tool) are JSON-RPC errors.
- Headers: send `Accept: application/json, text/event-stream` and `Content-Type: application/json`. Responses are JSON (no SSE stream). A browser GET returns 405 with a pointer here; it is not a connectivity test.
- Origin: requests with an `Origin` header are accepted only from this site, localhost or configured origins (403 otherwise).
- Auth: anonymous trial works without headers. An API key may be sent as `Authorization: Bearer sgk_live_...`. This was verified with the official SDK client (custom `requestInit` headers). OAuth is not implemented; clients that only support OAuth can use the anonymous trial.
- Quotas are shared with REST (see [auth and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md)); 429 responses carry `Retry-After`.
- Server card (experimental draft, SEP-2127): https://sunglassesguides.com/mcp/server-card

## Official SDK client example

```js
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(new StreamableHTTPClientTransport(new URL('https://sunglassesguides.com/mcp')));
const r = await client.callTool({ name: 'find_sunglasses', arguments: { reference_text: '52-18-140', require: { polarized: true } } });
console.log(r.structuredContent.result.status);
```

A complete script is in the repository: `examples/mcp-client.mjs`.

## Raw JSON-RPC

```sh
curl -sS -X POST https://sunglassesguides.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
curl -sS -X POST https://sunglassesguides.com/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_sunglasses_coverage","arguments":{}}}'
```