# AnyMCP

*Português: [README.pt.md](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](#what-does-not-exist-yet).

---

## 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).

## 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](docs/HOW-REMOTE-WORKS.md).

```mermaid
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](docs/GATEWAY.md).

## What is ready and how it was verified

| Part | What it does | How it was verified |
| --- | --- | --- |
| **Relay** (`src/relay`) | Device login, queue in Postgres, WebSocket doorbell, MCP endpoint, audit log | integration tests against a real PostgreSQL |
| **Agent** (`src/agent`) | Exposes any local MCP server (over stdio) through the relay; allow / deny / read-only policy | tests with a real agent and a real MCP server |
| **Security** | Secrets stored only as hashes, arguments and results encrypted at rest, rate limits, validation of everything that comes from the machines | 9 attack tests ([docs/SECURITY.md](docs/SECURITY.md)) |
| **Gateway** (`gateway/`) | Connect by link, multilingual search, response guard, JMESPath in the sandbox | 120 new tests (all pass) + a regression of 2,116 tests + an evaluation on the real catalog ([docs/GATEWAY.md](docs/GATEWAY.md)) |
| **Deployment** (`deploy/`) | Dockerfile, `docker-compose`, Caddy example | image built and run for real; device login performed against the container |

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](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](docs/MEASUREMENTS.md).

| What | Result |
| --- | --- |
| Calling a tool **directly** (no relay) | 0.7 ms (p50) |
| Calling **through the relay** (with WebSocket) | **45.7 ms (p50)**, 91 ms (p95) |
| Through the relay **without** WebSocket (only polling the table every 250 ms) | 293 ms (p50): the doorbell is worth it |
| Relay / Postgres memory at rest | 33 MiB / 30 MiB; 274 MB image |
| Tool search, top-1 hit rate (39 queries, catalog of 7,157 tools) | **31% → 97%** (Portuguese: 0% → 92%); English stays at 100% |
| Cost of the new search over the whole catalog | ~36 ms (before: ~11 ms) |
| A ~19 MB response reduced in the sandbox | the script receives less than 200 bytes; the 19 MB never enter the sandbox or the model |

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](docs/OPTIMIZERS.md).

## Try it

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

```bash
# 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](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](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

| Document | What it is for |
| --- | --- |
| [IDEA](docs/IDEA.md) | The idea in detail: the problem, the thesis, the principles, what we are not |
| [HOW THE REMOTE WORKS](docs/HOW-REMOTE-WORKS.md) | What we found out about Desktop Commander Remote, with file and line |
| [ARCHITECTURE](docs/ARCHITECTURE.md) | How AnyMCP is built: components, flows, database, failures, API |
| [GATEWAY](docs/GATEWAY.md) | The improvements for AnythingMCP and how to apply them |
| [MEASUREMENTS](docs/MEASUREMENTS.md) | All the numbers, methods and caveats |
| [OPTIMIZERS](docs/OPTIMIZERS.md) | What token optimizers actually claim × what was confirmed |
| [SECURITY](docs/SECURITY.md) | Threat model, controls, limits |
| [DEPLOYMENT](docs/DEPLOYMENT.md) | Putting it online |

## License and credits

**AGPL-3.0-only**, because the repository includes work derived from AnythingMCP (which uses that license). Full credits in [NOTICE.md](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.