From abee4dc32d4d30a783c665d9919f458fbb675e8f Mon Sep 17 00:00:00 2001 From: FilipBl4gojevic <84703395+FilipBl4gojevic@users.noreply.github.com> Date: Fri, 31 Jul 2026 15:26:28 +0200 Subject: [PATCH] docs: /mcp is the primary hosted endpoint - SSE stays as the deprecated compatibility pair --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 44 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index eb4aeff..4b13e6b 100644 --- a/README.md +++ b/README.md @@ -25,15 +25,36 @@ Hosted instances run on both networks, exposing all 24 tools: > (per-IP rate limiting, no token required) is a planned follow-up, not yet shipped. Self-host > this release for tokenless access today. +> **Transport: the hosted URLs above still answer on `/sse` only.** This codebase now serves +> a modern Streamable HTTP endpoint, `/mcp`, alongside `/sse` + `/messages` - the legacy SSE +> transport, deprecated by the MCP spec (2026-07-28 revision), retained for compatibility. +> `/mcp` becomes each hosted instance's primary endpoint once this release merges and deploys +> - testnet automatically on the next push to `main`, mainnet on the next deliberate cutover +> dispatch, the same split the migration above went through. Until then, +> `https://mcp.vector.mainnet.apexfusion.org/mcp` and its testnet twin are not reachable; +> self-host this release (below) to use `/mcp` today. + Connect from Claude Code in one command. Both hosted instances require a bearer token from the -operators (contact the Apex Fusion team for one): +operators (contact the Apex Fusion team for one). + +Modern transport (Streamable HTTP) - works today against a self-hosted instance (below); against +the hosted URLs above it goes live once each instance deploys this release (see the transport +note above): + +```bash +claude mcp add --transport http vector-mcp /mcp \ + --header "Authorization: Bearer " +``` + +Legacy SSE transport - what the hosted URLs above actually answer on today: ```bash claude mcp add --transport sse vector-mcp https://mcp.vector.mainnet.apexfusion.org/sse \ --header "Authorization: Bearer " ``` -Self-hosting (below) needs no token and gives every caller open access to your own instance. +Self-hosting (below) needs no token, gives every caller open access to your own instance, and +serves `/mcp` today. > **Security notice: the non-custodial migration is complete, in this codebase and on both > hosted instances, as of the 2026-07-31 cutover deploy.** No tool in this repository accepts a @@ -85,7 +106,7 @@ limitations. - **Agent messaging** - send on-chain messages between agents via TX metadata (keyless) - **Self-Improvement Module** - browse, submit, critique, and endorse improvement proposals; the on-chain module is live on Vector mainnet, and every write tool is keyless in this codebase - **Safety controls** - per-identity rate limiting; spend limits for every family are enforced by the local signer, per user - the server holds no spend-limit state of its own -- **SSE transport** - HTTP server with Server-Sent Events for MCP client connectivity +- **Dual transport** - modern Streamable HTTP (`/mcp`) plus legacy SSE (`/sse` + `/messages`, deprecated by the MCP spec (2026-07-28 revision), retained for compatibility) ## MCP Tools (24) @@ -170,6 +191,16 @@ npm start # Server listens on port 3000 (configurable via PORT env var) ``` +Connect with the modern transport: + +```bash +claude mcp add --transport http vector-mcp http://localhost:3000/mcp +``` + +Add `--header "Authorization: Bearer "` if you set `MCP_AUTH_TOKENS`. The legacy +SSE pair (`/sse` + `/messages`, deprecated by the MCP spec, retained for compatibility) is +still available at `http://localhost:3000/sse` for clients that need it. + If this instance will be reachable by anyone but you, set `MCP_AUTH_TOKENS` first - see [Configuration](#configuration) below. ### 4. Add to Claude Desktop @@ -223,10 +254,16 @@ it, lives in your local signer instead - see `VECTOR_SIGNER_SPEND_LIMIT_PER_TX` `VECTOR_SIGNER_SPEND_LIMIT_DAILY` / `VECTOR_SIGNER_AUDIT_LOG_PATH` in [`packages/signer/README.md`](packages/signer/README.md#configuration). -> **Running a public instance?** Set `MCP_AUTH_TOKENS`. Without it every caller -> is treated as one anonymous identity and shares a single rate-limit bucket, so -> one busy client throttles everyone. Rate limits are applied per identity, so -> give each client its own token. +> **Running a public instance?** Set `MCP_AUTH_TOKENS` to gate access to known callers, each +> with its own rate-limit budget. With `MCP_AUTH_TOKENS` unset, callers are admitted +> anonymously with per-client-IP rate limits; the deployment's reverse proxy supplies the +> client address via the rightmost X-Forwarded-For entry. Tracked identities are capped (LRU); +> eviction resets a bucket's budget - a memory bound, not a security boundary, since an +> attacker rotating enough source IPs can still defeat per-IP limiting at a tier only the +> reverse proxy or network layer can police. `/mcp` sessions get the same per-identity +> treatment: idle sessions are reaped after `VECTOR_MCP_SESSION_IDLE_MS` (default 10 minutes), +> and concurrent sessions per identity are capped at `VECTOR_MCP_MAX_SESSIONS_PER_IDENTITY` +> (default 32). > **Malformed values fail loudly, not silently.** The server refuses to start if > `MCP_AUTH_TOKENS` contains an empty token, a token with embedded whitespace, a