Any MCP client

Any client that speaks the Model Context Protocol over Streamable HTTP can use Routeur: point it at https://api.routeur.app/mcp, add the key header, and it will find 38 tools, 7 resources plus one template, and 3 prompts. This page shows the protocol at the level of HTTP requests, so you can check a client’s behaviour or write your own, and the mcp-remote bridge for clients that only launch stdio servers. Every example was run against the live server on 2026-09-17.

The endpoint

POST https://api.routeur.app/mcp, JSON-RPC 2.0 over Streamable HTTP. The server is stateless: it sets no Mcp-Session-Id, keeps nothing between requests, answers GET /mcp with 405, and returns plain application/json rather than an event stream because no tool streams.

Header	Value	Observed behaviour
`Authorization`	`Bearer <your API key>` (or `X-API-Key: <key>`)	Missing: `401` with `WWW-Authenticate: Bearer realm="routeur"`. Unknown or revoked key: `401`.
`Content-Type`	`application/json`	Required.
`Accept`	`application/json, text/event-stream`	`Accept: application/json` alone is refused with `400 Accept must contain both 'application/json' and 'text/event-stream'`. Omitting the header (curl’s default `/`) is accepted, but send both explicitly; SDK clients do.
`MCP-Protocol-Version`	The version `initialize` returned, on every later request	Optional for this server. `2025-06-18` and `2025-11-25` work as-is. `2026-07-28` in this header makes the server require that revision’s `_meta` fields on every request (`400 missing or invalid _meta field "io.modelcontextprotocol/protocolVersion"`), so only send it if your client implements that revision fully. An unknown version gets `400 Unsupported protocol version`.

The protocol with curl

Initialize

curl -s https://api.routeur.app/mcp \
  -H "Authorization: Bearer $ROUTEUR_API_KEY" \
  -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":"my-agent","version":"1.0.0"}}}'

Observed response, trimmed (the instructions text is the full three-paragraph summary the server gives every client):

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "logging": {}, "prompts": {"listChanged": true}, "resources": {"listChanged": true}, "tools": {"listChanged": true} },
    "serverInfo": { "name": "routeur", "title": "Routeur prediction markets", "version": "2026-09-15", "websiteUrl": "https://routeur.app" },
    "instructions": "Routeur proves which prediction-market contracts on Kalshi and Polymarket imply, exclude or equal each other ... Everything is read-only and nothing here places orders."
  }
}

Asking for 2026-07-28 is answered with 2025-11-25; the server negotiates down to the newest revision both sides speak. Because the server is stateless, the notifications/initialized message is accepted (202, no body) but changes nothing, and initialize itself is not required before tools/call: every example on this page was run as a single request.

List the tools

curl -s https://api.routeur.app/mcp \
  -H "Authorization: Bearer $ROUTEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Observed: 38 tools, each with name, title, description, inputSchema and annotations {"readOnlyHint": true, "idempotentHint": true, "destructiveHint": false, "openWorldHint": false}. Tool descriptions state what each call costs. tools/list is authenticated but not metered.

Call a tool

curl -s https://api.routeur.app/mcp \
  -H "Authorization: Bearer $ROUTEUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
        "name":"search_markets",
        "arguments":{"query":"detroit buffalo total points","cross_venue":true,"limit":1}}}'

Observed result, trimmed. The JSON is returned twice: as content[0].text for clients that only read text, and as structuredContent for clients that read objects.

{
  "jsonrpc": "2.0", "id": 3,
  "result": {
    "content": [{ "type": "text", "text": "{\n  \"filters\": [ ... ],\n  \"results\": [ ... ]\n}" }],
    "structuredContent": {
      "query": "detroit buffalo total points",
      "filters": [{ "kind": "cross_venue", "label": "On both venues", "value": "true" }],
      "graph_run": 74,
      "next_cursor": "MQ",
      "results": [{
        "match": "match", "venue": "polymarket", "event_id": "810546",
        "title": "Detroit vs Buffalo: Total Points", "venues": ["kalshi", "polymarket"],
        "closes_at": "2026-09-18T00:15:00Z", "volume_24h_usd": "1518274.93",
        "outcomes": [{
          "label": "O/U 54.5", "chance": "0.5200", "best_venue": "kalshi",
          "prices": [
            { "venue": "kalshi", "market_id": "KXNFLTOTAL-26SEP17DETBUF-55", "yes_ask_usd": "0.52", "no_ask_usd": "0.49", "observed_at": "2026-09-17T12:33:03.021417Z" },
            { "venue": "polymarket", "market_id": "nfl-det-buf-2026-09-18-total-54pt5", "yes_ask_usd": "0.53", "no_ask_usd": "0.48", "observed_at": "2026-09-17T12:31:00.831305Z" }
          ]
        }]
      }]
    }
  }
}

Pass next_cursor back as cursor for the next page. Endpoint tools (get_market, list_relations, …) return the REST body unchanged, including its data envelope and graph_run.

Errors are tool results, not protocol errors

A failed call comes back with isError: true and a readable message, so the model can act on it; the HTTP status is still 200. Observed:

Call	`content[0].text`
`get_market` with `id: "DOES-NOT-EXIST"`	`GET /v1/markets/kalshi/DOES-NOT-EXIST answered 404 market_not_found: The market is not in the latest graph.`
`market_snapshot` with an extra argument `bogus`	`unknown argument(s) bogus; this tool takes days, detail, id, venue`
Any tool over the per-minute limit	A message naming `rate_limited` and the seconds to wait (`daily_quota_exceeded` for the day’s quota)

Protocol-level mistakes are reported differently, as observed:

Request	Response
`tools/call` with an unknown tool name	HTTP `200`, JSON-RPC error `-32602 unknown tool "nope"`
Unknown method	HTTP `400`, `JSON RPC not handled: "nope" unsupported`
Body that is not JSON	HTTP `400`, `malformed payload: ...`
`Accept` without both media types, or an unsupported `MCP-Protocol-Version`	HTTP `400` with the reason in the body
A notification such as `notifications/initialized`	HTTP `202` with no body
Missing, unknown or revoked key	HTTP `401`

Resources and prompts

# The four concept pages cost nothing; the three live lists cost one request each.
-d '{"jsonrpc":"2.0","id":4,"method":"resources/list"}'
-d '{"jsonrpc":"2.0","id":5,"method":"resources/read","params":{"uri":"routeur://concepts/prices"}}'
-d '{"jsonrpc":"2.0","id":6,"method":"resources/templates/list"}'     # routeur://topics/{slug}
-d '{"jsonrpc":"2.0","id":7,"method":"prompts/list"}'
-d '{"jsonrpc":"2.0","id":8,"method":"prompts/get","params":{"name":"brief_me_on_event","arguments":{"event":"Detroit vs Buffalo total points"}}}'

resources/list returns routeur://categories, routeur://concepts/glossary, routeur://concepts/leads-and-fees, routeur://concepts/prices, routeur://concepts/relations, routeur://openapi.json and routeur://topics; concept pages are text/markdown, the rest application/json. prompts/get returns one user message whose text is a numbered plan naming the tools to call and the caveats to state.

SDK clients

Any MCP SDK works: use its Streamable HTTP transport and add the header.

TypeScript

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(new URL('https://api.routeur.app/mcp'), {
  requestInit: { headers: { Authorization: `Bearer ${process.env.ROUTEUR_API_KEY}` } },
});
const client = new Client({ name: 'my-agent', version: '1.0.0' });
await client.connect(transport);

const { tools } = await client.listTools();                     // 38
const snapshot = await client.callTool({
  name: 'market_snapshot',
  arguments: { venue: 'kalshi', id: 'KXNFLTOTAL-26SEP17DETBUF-55', days: 7 },
});
console.log(snapshot.structuredContent);

package main

import (
    "context"
    "fmt"
    "net/http"
    "os"

    "github.com/modelcontextprotocol/go-sdk/mcp" // v1.8.0, the version Routeur's own server uses
)

type keyed struct{ key string }

func (k keyed) RoundTrip(r *http.Request) (*http.Response, error) {
    clone := r.Clone(r.Context())
    clone.Header.Set("Authorization", "Bearer "+k.key)
    return http.DefaultTransport.RoundTrip(clone)
}

func main() {
    client := mcp.NewClient(&mcp.Implementation{Name: "my-agent", Version: "1.0.0"}, nil)
    transport := &mcp.StreamableClientTransport{
        Endpoint:             "https://api.routeur.app/mcp",
        HTTPClient:           &http.Client{Transport: keyed{os.Getenv("ROUTEUR_API_KEY")}},
        DisableStandaloneSSE: true, // the server is stateless and answers GET with 405
    }
    session, err := client.Connect(context.Background(), transport, nil)
    if err != nil {
        panic(err)
    }
    defer session.Close()

    res, err := session.CallTool(context.Background(), &mcp.CallToolParams{
        Name:      "search_markets",
        Arguments: map[string]any{"query": "detroit buffalo total points", "cross_venue": true, "limit": 1},
    })
    if err != nil {
        panic(err)
    }
    fmt.Println(res.IsError, res.StructuredContent)
    // session.ListTools, session.ReadResource and session.GetPrompt work the same way.
}

The Go field and method names were checked against go-sdk v1.8.0; the TypeScript transport options are the SDK’s documented requestInit form.

stdio-only clients

Clients that can only launch a local process reach the server through mcp-remote, which speaks stdio to the client and Streamable HTTP to Routeur. Pass the header through an environment variable: several clients do not escape spaces inside args, and Authorization: Bearer ... has one.

{
  "mcpServers": {
    "routeur": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.routeur.app/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer rk_live_..." }
    }
  }
}

--transport http-only skips the fallback to the older SSE transport, which Routeur does not serve. mcp-remote runs on your machine and holds the key in its process; the traffic still goes to api.routeur.app over TLS. Prefer a native remote connection where your client supports one.

Discovery

https://api.routeur.app/.well-known/mcp.json (also served at /.well-known/mcp/server-card.json, and mirrored at https://routeur.app/.well-known/mcp.json) describes the server without a key: endpoint, transport, protocol versions, how to authenticate, capabilities {tools, resources, prompts, readOnly} and the name and first line of every tool. https://routeur.app/llms.txt and /llms-full.txt say the same in plain text for agents that read a site before using it.

Agents & MCP: what a tool call costs and the three surfaces.
Tool reference: every tool’s arguments, defaults and ranges.
Authentication, Rate limits, Errors and conventions.

Get started

Concepts

Agents & MCP

Webhooks

Reference

The endpoint

The protocol with curl

Initialize

List the tools

Call a tool

Errors are tool results, not protocol errors

Resources and prompts

SDK clients

stdio-only clients

Discovery

The endpoint

The protocol with curl

Initialize

List the tools

Call a tool

Errors are tool results, not protocol errors

Resources and prompts

SDK clients

stdio-only clients

Discovery

Related