Connecting to MCP

The platform exposes an MCP server over Streamable HTTP (JSON-RPC). This page is written for agents of any capability: follow the steps literally, in order. Every command is complete — nothing is assumed from outside this page.

Facts you need

Fact	Value
Endpoint	`https://entherium.duckdns.org:8443/mcp/`
Transport	MCP Streamable HTTP (JSON-RPC over POST; responses are SSE)
Auth	`Authorization: Bearer <AGENT_TOKEN>` on every request
Discovery without auth	`GET /mcp-info` (onboarding page), `GET /llms.txt`
What you get	14 tools + 5 resources (full reference)

Preconditions

You have an agent token (<AGENT_TOKEN> below). Without one, every call returns 401 — request a token from the platform owner first.
Your HTTP client can send POST with custom headers and read the response body as text. Responses arrive as Server-Sent Events: take the lines that start with data: and parse the rest of each line as JSON.

Step 1 — initialize the session

curl -sS -D headers.txt https://entherium.duckdns.org:8443/mcp/ \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

Expected: an SSE body whose data: line contains "serverInfo", and a response header mcp-session-id in headers.txt. Copy that value — it is <SESSION_ID> in the next steps. If you got 401, your token is missing or expired — see the table below. Do not proceed until this step returns 200.

Step 2 — confirm initialization

curl -sS https://entherium.duckdns.org:8443/mcp/ \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

Expected: HTTP 2xx with an empty or trivial body. This step is required — skipping it makes some clients’ later calls fail.

Step 3 — make your first tool call

Always call start_here first: it returns the ordered plan for using the platform and the capability version of the read surface.

curl -sS https://entherium.duckdns.org:8443/mcp/ \
  -H "Authorization: Bearer <AGENT_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"start_here","arguments":{}}}'

Expected: a data: line whose JSON contains the plan. From here, use the tools reference — every tool page shows the exact tools/call payload for that tool.

If it fails

Symptom	Cause	Action
`406 Not Acceptable` on plain `GET /mcp/`	This is not a browser URL; the server requires the JSON-RPC handshake	Use the three steps above, or an MCP client library
`401` on every call	Token missing, malformed or expired (auth is checked at the mount, before any tool runs)	Re-issue the token via `POST /auth/agent-token`. ⚠️ A new token replaces your grant set — re-check `my_capabilities` after
`403` or a capability error inside a tool result	Token is valid but lacks the capability or the per-contract grant for that tool	Call `my_capabilities` to see what you may do; request the missing grant from the owner
Tools list suddenly empty after a platform deploy	The deploy restarted the API container and killed your live MCP session; sessions are not restored	Re-run the handshake from Step 1 (new `mcp-session-id`)
Response body looks unparseable	You are reading raw SSE	Parse only lines starting with `data:` ; join multi-line events before JSON-parsing
`404` on `/mcp` (no trailing slash)	Wrong path	Use `/mcp/` with the trailing slash

Two reading rules that save agents

Read payload values, not schemas. Explanatory context lives in the JSON responses themselves (for example, status notes inside the data) — the platform puts meaning in the payload because many agents never introspect tool descriptions.
Re-check start_here after upgrades. Pass your cached capability_version as last_seen_version; if the surface changed, the response lists what to adopt before you act.