{"_id":"@allotly/mcp","name":"@allotly/mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@allotly/mcp","version":"0.1.0","type":"module","description":"Stdio bridge to Allotly's hosted MCP server","bin":{"allotly-mcp":"dist/index.js"},"main":"./dist/index.js","scripts":{"build":"tsc && node scripts/postbuild.mjs","test":"vitest run","prepublishOnly":"npm run build"},"engines":{"node":">=18"},"dependencies":{"mcp-remote":"^0.1.38"},"devDependencies":{"typescript":"^5.6.0","@types/node":"^20.0.0","vitest":"^3.2.0"},"keywords":["mcp","allotly","ai","model-context-protocol","stdio","bridge"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/tiagomaranhaoalves/Allotly.git","directory":"packages/allotly-mcp"},"homepage":"https://allotly.ai","bugs":{"url":"https://github.com/tiagomaranhaoalves/Allotly/issues"},"_id":"@allotly/mcp@0.1.0","gitHead":"b9d958db16bae7f84725ceffd1e59b8a6bb47166","types":"./dist/index.d.ts","_nodeVersion":"22.11.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-hzjEScK/VmNp6jm66Lf12OPzAYYen5g8a2W4zJNX1qCjc4Vn2cTYzxrkT9MyUfE8SZsHDou7d6eBW7FXnU8JdQ==","shasum":"892445e3d1065a78480f92ad972c17c1c2da4247","tarball":"https://registry.npmjs.org/@allotly/mcp/-/mcp-0.1.0.tgz","fileCount":5,"unpackedSize":15366,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEndSMQSKVLfNdsoTRFHfbeRLjCJPjYCOz04KAGFZeqjAiEAqaywMKqCwGy5YEUi3MI4X3i2zTLNdF2xMcH9bPEv5n0="}]},"_npmUser":{"name":"allotlydev","email":"tiagomaranhaoalves14nov@gmail.com"},"directories":{},"maintainers":[{"name":"allotlydev","email":"tiagomaranhaoalves14nov@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.1.0_1777221903524_0.6579413374191194"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T16:45:03.434Z","0.1.0":"2026-04-26T16:45:03.690Z","modified":"2026-04-26T16:45:03.988Z"},"maintainers":[{"name":"allotlydev","email":"tiagomaranhaoalves14nov@gmail.com"}],"description":"Stdio bridge to Allotly's hosted MCP server","homepage":"https://allotly.ai","keywords":["mcp","allotly","ai","model-context-protocol","stdio","bridge"],"repository":{"type":"git","url":"git+https://github.com/tiagomaranhaoalves/Allotly.git","directory":"packages/allotly-mcp"},"bugs":{"url":"https://github.com/tiagomaranhaoalves/Allotly/issues"},"license":"MIT","readme":"# @allotly/mcp\n\nA tiny stdio-to-HTTP bridge that connects [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh), [Claude Code](https://docs.anthropic.com/claude-code), [VS Code](https://code.visualstudio.com), and other MCP hosts to **Allotly**'s hosted MCP server at `https://allotly.ai/mcp`.\n\n## What is Allotly?\n\n[Allotly](https://allotly.ai) is an AI spend control plane. You issue an `allotly_sk_...` key to your team, your assistant, or your agent; Allotly enforces budgets, model allowlists, and per-key spending caps; the same key works across OpenAI, Anthropic, Google Gemini, and Azure OpenAI.\n\nThis package gives MCP hosts that only speak **stdio** (Claude Desktop, Cursor's stdio mode, Claude Code, VS Code) the ability to call Allotly's MCP tools. The hosted server itself speaks Streamable HTTP — this bridge translates between the two.\n\n## What you get\n\nOnce connected, your assistant can call these Allotly tools:\n\n| Tool | What it does |\n| --- | --- |\n| `list_available_models` | Models your key is allowed to use, with pricing |\n| `chat` | Send a chat completion through Allotly's proxy |\n| `compare_models` | Run the same prompt across models, compare cost & latency |\n| `recommend_model` | Suggest a cheaper model that fits your task |\n| `voucher_info` | Inspect a voucher code (no auth needed) |\n| `my_budget` | Remaining budget on your key |\n| `my_status` | Health, key info, and recent activity |\n| `my_recent_usage` | Last N requests with cost breakdown |\n| `diagnose` | Diagnose a failing request |\n| `quickstart` | Step-by-step onboarding for a new user |\n| `redeem_voucher` | Turn a voucher into a usable key |\n| `redeem_and_chat` | Redeem a voucher and immediately chat |\n| `request_topup` | Ask your team admin for more budget |\n\nAll tool responses include `_meta.budget` so the host can show you remaining spend in real time.\n\n## Install\n\nYou don't install this package globally. Your MCP host runs it on demand via `npx`. The configuration snippets below take care of everything.\n\nYou will need:\n\n1. An Allotly API key (`allotly_sk_...`). [Get one here](https://allotly.ai/dashboard/keys), or [redeem a voucher](https://allotly.ai/redeem).\n2. Node.js 18 or newer on your machine (for `npx` to work).\n\n## Claude Desktop\n\nEdit `claude_desktop_config.json`:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"allotly\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@allotly/mcp\"],\n      \"env\": {\n        \"ALLOTLY_KEY\": \"allotly_sk_...\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The Allotly tools will appear in the tools menu.\n\n## Cursor\n\nEdit `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):\n\n```json\n{\n  \"mcpServers\": {\n    \"allotly\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@allotly/mcp\"],\n      \"env\": {\n        \"ALLOTLY_KEY\": \"allotly_sk_...\"\n      }\n    }\n  }\n}\n```\n\nOpen the Cursor command palette and run **MCP: Reload Servers**.\n\n## Claude Code\n\nClaude Code can speak HTTP MCP directly, so you don't strictly need this bridge — but if you prefer to use it for consistency:\n\n```bash\nclaude mcp add allotly npx -y @allotly/mcp \\\n  --env ALLOTLY_KEY=allotly_sk_...\n```\n\nOr, the native HTTP path:\n\n```bash\nclaude mcp add --transport http allotly https://allotly.ai/mcp \\\n  --header \"Authorization: Bearer allotly_sk_...\"\n```\n\n## VS Code (with the MCP extension)\n\nEdit your VS Code `settings.json`:\n\n```json\n{\n  \"mcp.servers\": {\n    \"allotly\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@allotly/mcp\"],\n      \"env\": {\n        \"ALLOTLY_KEY\": \"allotly_sk_...\"\n      }\n    }\n  }\n}\n```\n\n## Environment variables\n\n| Variable | Required | Default | Notes |\n| --- | --- | --- | --- |\n| `ALLOTLY_KEY` | yes | — | Your Allotly API key (`allotly_sk_...`). The bridge refuses to start without it. |\n| `ALLOTLY_MCP_URL` | no | `https://allotly.ai/mcp` | Override the hosted endpoint. Useful for self-hosted Allotly or staging. |\n\n## How it works\n\nThis package wraps [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) — a generic stdio↔HTTP MCP bridge — and pre-configures it for Allotly. When your MCP host launches `npx -y @allotly/mcp`:\n\n1. The bridge reads `ALLOTLY_KEY` from the environment your host passes in.\n2. It spawns `mcp-remote` against `https://allotly.ai/mcp` with `Authorization: Bearer <ALLOTLY_KEY>`.\n3. `stdin`/`stdout` are forwarded to your host transparently. JSON-RPC requests flow over HTTP to Allotly; responses flow back unchanged.\n4. `stderr` from `mcp-remote` is prefixed with `[allotly-mcp]` so you can tell our diagnostic logs apart from the bridge's own.\n5. `SIGINT` / `SIGTERM` are forwarded so the bridge exits cleanly when your host shuts down.\n\nYour `allotly_sk_...` key never appears in `stdout`, never crosses host process boundaries beyond the spawned bridge, and never reaches the model providers — only Allotly sees it.\n\n## Security notes\n\n- **`ALLOTLY_KEY` is passed to `mcp-remote` on its command line** as `--header \"Authorization: Bearer <key>\"`. This means the key is briefly visible in process listings (`ps`, `/proc/<pid>/cmdline`, Activity Monitor) to **other processes running as the same OS user on the same machine**. It does not cross network or user boundaries. If you consider local-process-listing exposure a threat in your environment, do not use this bridge from that machine; instead, point your host directly at the HTTP endpoint (Claude Code supports this — see above).\n- The key never appears on `stdout` and is never sent to the model providers — only to Allotly.\n- A future release of this package will switch to `mcp-remote`'s programmatic API once it exposes a non-argv way to pass headers, eliminating the listing exposure entirely. Track [issue tracker](https://github.com/tiagomaranhaoalves/Allotly/issues) for updates.\n- All other secret-handling guarantees of the hosted MCP server still apply: `voucher_info` is the only unauthenticated tool, redacted log lines never contain `allotly_sk_…`, and audit-log writes happen out of band.\n\n## Troubleshooting\n\n**`ALLOTLY_KEY is not set`** — Your host isn't passing the env var. Double-check the `env` block in your config matches the snippet exactly. Restart your host after editing.\n\n**`Authentication failed` from `mcp-remote`** — Your key is invalid, expired, or revoked. Check the key on your [Allotly dashboard](https://allotly.ai/dashboard/keys).\n\n**No tools appear in Claude Desktop** — Open the developer settings and check the MCP log. Most issues are JSON syntax errors in `claude_desktop_config.json`.\n\n**Behind a corporate proxy** — `mcp-remote` honours the standard `HTTPS_PROXY` env var. Add it to the `env` block of your host config.\n\n## Source\n\nThis is a thin bridge. The interesting code is the hosted server — its source and protocol details live in the [Allotly repo](https://github.com/tiagomaranhaoalves/Allotly).\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-39396a6bc2a18e9db6acbf51bf32d1b9"}