AnyMCP

Português: README.pt.md.

Paste a link and everything connects. Big data stays out of the model. It runs on a server that costs almost nothing.

This repository explains an idea and ships a prototype that backs it up: how to let an AI use tools that live on your own computer or on any MCP server, without opening a port, without a tunnel and without depending on a third-party service, and how to stop huge responses (50 KB to 44 MB) from flowing through the model.

Status: a working, tested prototype, not a finished product. Every claim below says how it was verified. What was not verified is marked, and the list of what does not exist yet is further down.

The problem, in five points

1. Connecting is work. In AnythingMCP, wiring up an MCP server means creating the connector, authorizing it and discovering its tools, in separate steps.

2. Machines behind NAT are unreachable. Desktop Commander solves this with a hosted service (mcp.desktopcommander.app, in beta). It works, but your commands and results pass through a third party.

3. Big responses blow up the context. According to the description of the Codebound challenge, in production about 1 in 8 calls returns more than 50 KB, and the largest returns 44 MB. All of that used to flow into the model.

4. Tool search broke on accents. "gestão de preços" ("price management") became ["gest","de","pre","os"]. In Portuguese, the AI could not find the right tool.

5. Cost. How much server does all this take? We measured: about 63 MiB of memory at rest (relay 33 + Postgres 30).

Related MCP server: MCP Tool Manager

The idea

We studied how the Remote feature of Desktop Commander works inside (the published package, version 0.2.52, MIT license) and extracted what makes it work well even in beta:

• the machine only makes outbound connections, so it needs no open port;

• a real-time notification (the doorbell) only wakes the machine up, and the database table is the truth: if the notification is lost, nothing is lost;

• every call is claimed atomically: exactly one machine runs it;

• there is layered recovery (reconnection with growing waits, detection of a stuck channel, credential renewal);

• the machine itself decides what it exposes.

AnyMCP reuses these principles (except credential renewal, which we replaced with tokens that the owner can revoke) with parts you already have on an ordinary server: PostgreSQL (LISTEN/NOTIFY instead of Supabase Realtime) and WebSocket. Details and evidence in docs/HOW-REMOTE-WORKS.md.

flowchart LR
    C["MCP client<br/>(Claude, Cursor, AnythingMCP...)"] -- "HTTPS + token" --> R
    subgraph VPS["Your server (1 VPS)"]
      R["Relay<br/>(Node + WebSocket)"] <--> P[("PostgreSQL<br/>call queue")]
    end
    A["Agent<br/>(on your machine)"] -. "OUTBOUND connection<br/>(WebSocket + HTTPS)" .-> R
    A -- "stdio" --> L["Local MCP server<br/>(Desktop Commander, or any other)"]

Plus the gateway side: patches for AnythingMCP that provide connection by link, multilingual search, protection against huge responses, and processing of big data inside the Codebound sandbox. See docs/GATEWAY.md.

What is ready and how it was verified

For the relay and the agent, the whole suite runs with npm test (it needs a PostgreSQL at TEST_DATABASE_URL). We also simulated what continuous integration would do (clean copy, npm ci, npm run typecheck, npm test): everything passed. This repository does not have continuous integration on GitHub yet. Results and caveats in docs/MEASUREMENTS.md.

Measured numbers

All measured by us, on 17 Oct 2026, on a 6-CPU server (AMD EPYC) that was running other applications at the same time (load average 4 to 6). These are measurements from one machine, not guarantees. Methods and caveats in docs/MEASUREMENTS.md.

And one fact that dismantles a common assumption: the catalog of 474 adapters does not go to the AI as a whole. If someone exposed all of it, it would be 5.04 MB (~1.32 million estimated tokens), which is impossible. A typical adapter has 11 tools and ~1,700 tokens; AnythingMCP's shared /mcp endpoint exposes only 8 tools (~1,300 tokens). The context cost depends on how many connectors you attach to a server. That is why you should measure before installing any token optimizer.

Try it

You need Docker (for the relay) and Node 22.18 or newer (for the agent).

# 1. Start the relay (PostgreSQL + relay). Fill in deploy/.env: the commands that generate the secrets are in the file.
cp deploy/.env.example deploy/.env
docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d --build
# For HTTPS, put Caddy in front: deploy/Caddyfile.example

# 2. On the machine you want to reach
git clone https://github.com/LORD998/AnyMCP && cd AnyMCP && npm ci
node src/agent/main.ts login --relay https://relay.example.com --name laptop
#   shows a code; you approve it at https://relay.example.com/device with the owner secret
node src/agent/main.ts run --read-only -- node test/fixtures/echo-server.ts
#   instead of the example server, any MCP server over stdio

# 3. Create a token and connect an MCP client
curl -X POST https://relay.example.com/v1/tokens \
  -H "authorization: Bearer $RELAY_OWNER_SECRET" -H "content-type: application/json" \
  -d '{"label":"my-client","allow":["laptop__*"]}'
#   MCP address: https://relay.example.com/mcp   header: Authorization: Bearer <token>

Full walkthrough, with Caddy and checks, in docs/DEPLOYMENT.md.

What does not exist yet

Said plainly, so nobody is misled:

• Not tested with the real Desktop Commander. The agent was designed to expose any MCP server over stdio and was tested with an example MCP server; running Desktop Commander through it is the next test, not yet done. Desktop Commander gives access to the terminal and to files: use explicit --allow/--deny, restrict its folders, and remember that --read-only depends on the readOnlyHint annotations that the server itself declares.

• No MCP OAuth. The relay authenticates with a fixed token in the Authorization header. Clients that only accept OAuth (for example, the custom connectors of Claude's web interface) cannot use it yet. Clients that accept a fixed header (Claude Code, editors, AnythingMCP itself) should be able to, but we did not test with them: the tests use the official MCP SDK client.

• No end-to-end encryption. MCP clients do not encrypt the arguments, so the relay sees them. Encryption at rest protects against a leaked database or backup, not against a compromised relay. That is why the relay must be yours. See docs/SECURITY.md.

• A single owner. No users, no web dashboard, no automatic token rotation.

• No cancellation or progress for a call that is already running on the machine. The relay waits for the machine for 60 s per call (CALL_TIMEOUT_MS, configurable): if the call takes longer, the client gets a notice and the result is not returned to it.

• The full gateway (the whole AnythingMCP + database) was not brought up end to end with the patches. The unit and integration tests of the changed parts pass, and the patches apply cleanly, but the proof with the whole application running is left for later.

• Tests on Linux only. The agent should work on macOS and Windows (it is plain Node), but it was not tested there.

• The search evaluation uses 39 queries and criteria written by us; they are in gateway/eval/ so they can be challenged.

Repository map

docs/        the explanation, in English (start with IDEA.md)
docs/pt/     the same explanation, in Portuguese (start with IDEIA.md)
src/relay/   the relay: queue, login, doorbell, MCP endpoint
src/agent/   the agent that runs on your machine
src/shared/  cryptography, tool filters, reconnection, response limit
test/        unit, integration and security tests (real PostgreSQL)
gateway/     patches for AnythingMCP + complete files + search evaluation
bench/       reproducible measurements (relay latency, size of the catalog and of the tool list)
deploy/      Dockerfile, docker-compose, Caddy example

Documents

License and credits

AGPL-3.0-only, because the repository includes work derived from AnythingMCP (which uses that license). Full credits in NOTICE.md: AnythingMCP (HelpCode.ai), the Codebound sandbox from the collaborators of sidag99/anythingmcp, and Desktop Commander (MIT), which we studied and from which we copied no code.