Vibocode MCP

vibocode-mcp

Two tools instead of an API catalog. An MCP server that keeps the agent's context small and its reach long.

search  — finds the right endpoints and memory facts, returns compact signatures

run — executes model-written Python in a sandbox: api.get(path) + vi.add/find/stats

The whole toolset is 217 tokens (o200k_base tokenizer). The same GitHub REST catalog — 1,272 endpoints — costs 79,525 tokens as plain MCP tools: a 366x difference. Slack's 174 endpoints: 42x. Measurements and reproduction commands are in Benchmarks.

Install

npx vibocode-mcp

Requires Node 18+ and Python 3.10+ (the server is Python).

MCP client configuration:

{

"mcpServers": { "vibocode": { "command": "npx", "args": ["-y", "vibocode-mcp"], "env": { "VIBOCODE_CATALOG": "/path/to/catalog.json", "VIBO_MEM_FILE": "/path/to/memory.web" } } } }

Action catalog

catalog.json describes a service: base URL, allowed domains and the list of actions.

{

"service": "example", "base_url": "http://127.0.0.1:4174", "allow_domains": ["127.0.0.1"], "actions": [ {"name": "health", "method": "GET", "path": "/api/health", "auth": false, "desc": "Service health: storage, notification channels, server time"} ] }

The catalog is not written by hand: for OpenAPI it is generated.

python3 tools/openapi_to_catalog.py openapi.json -o catalog.json \

--base-url https://api.example.com --allow api.example.com --service example

What it looks like in use

h = api.get("/api/health")

print(h["status"], h"data") vi.add("Service health", "health ok, storage local-json") print(vi.stats())

One run call: an API request, a memory write and a stats read. Without memory it is just a sandbox; the value is that the next session does not rediscover what is already known.

What is inside

bin/vibocode-mcp.js        — npm entry point (starts the Python server)

vibocode/server.py — MCP server (JSON-RPC over stdio) vibocode/catalog.py — catalog search, compact signatures vibocode/aliases.json — query alias data (natural language -> catalog terms) vibocode/bridge.py — bridge: ViBo memory + allowlisted HTTP vibocode/sandbox.py — AST validation + isolated process with limits vibocode/runner.py — model code executor tools/openapi_to_catalog.py — catalog generator from OpenAPI tests/test_mcp.py — 19 checks skill/ — packaging as an agent skill (SKILL.md + CLI)

Security

• imports: json, math, re, datetime, statistics, itertools
• forbidden: open, eval, exec, compile, __import__, getattr, setattr, dunder attributes, global/nonlocal, infinite loops
• network: only api.get(path), only hosts from allow_domains
• limits: 40 s wall clock, 1.5 GB memory, 20 s CPU, output capped at 4,000 characters
• writing the same fact to memory twice is skipped

This is a Python-level sandbox (AST + rlimits + a separate process), not a V8 isolate: it protects against accidental and careless code, not against a deliberate OS-level attack.

Tests

python3 tests/test_mcp.py     # protocol, search, memory, API, limits, blocks

Benchmarks

Tokenizer: o200k_base (tiktoken). Catalogs are generated from official OpenAPI specs. "Full catalog" means one tool per endpoint, with name, description and an empty input schema — the lower bound, generous to the alternative.

For GitHub this is 40% of a 200,000-token window before the user says a word.

End-to-end: one run call with 196 tokens of code performed three requests to api.github.com, wrote a fact to memory and read the stats back. The whole five-step exchange: 2,202 tokens.

Search quality

Search is lexical and alias-aware. aliases.json maps the words a user types to catalog terms, so a query can be phrased naturally rather than in endpoint vocabulary.

Shipped configuration (English aliases):

With a language pack loaded through VIBOCODE_ALIASES (a mixed 28-query set, half of it non-English): Stripe 80% / 95%, GitHub 38% / 75%.

Known weakness in both cases: queries that describe a whole scenario instead of an object. Next step: hybrid BM25 + embeddings.

Limitations

• transport is line-delimited JSON-RPC (not Content-Length); sufficient for stdio clients
• session-based endpoints need a cookie or a service token
• the catalog is static: new endpoints are added to catalog.json (or generated from OpenAPI)
• search is lexical, without a vector index

License

MIT. ViBo memory is a separate product with its own license.