MCP Server Documentation

Connect a Host

Allotly's MCP server supports OAuth 2.0. Most modern MCP hosts handle OAuth automatically — just add the server URL and authenticate when prompted.

Cursor

Add Allotly as an HTTP MCP server inside Cursor's settings. Config file: ~/.cursor/mcp.json

VS Code

Configure Allotly as an HTTP MCP server in VS Code's MCP settings. Config file: .vscode/mcp.json

Claude Code (CLI)

Register Allotly with one shell command using the Claude Code CLI.

Codex CLI

Add Allotly to your Codex CLI config. Config file: ~/.codex/config.toml

Claude Desktop

Use the @allotly/mcp bridge package over stdio. Config file: claude_desktop_config.json

Available Tools

Consumption Tools

• chat — Send messages to any AI model your Allotly key allows. Returns the assistant's reply and your remaining budget. Supports system prompts, temperature, JSON mode, tool calling, vision input, and streaming.
• list_available_models — List the AI models your Allotly key is allowed to use, with pricing and capabilities.
• compare_models — Send the same prompt to multiple models in parallel and get all answers side-by-side.
• recommend_model — Suggest the best model for a task given your remaining budget.
• estimate_cost — Read-only cost preview for a prompt before you spend a token.

Recipient Tools

• quickstart — Get a friendly intro to your Allotly access — models, remaining budget, expiry, and sample prompts.
• my_status — Show your budget, concurrency state, and rate limit state in one view.
• my_budget — Show your current remaining budget, total budget, period end, and requests remaining.
• my_recent_usage — List your recent API calls with model, cost, and timestamp.
• diagnose — Explain in plain English what went wrong with your most recent failed API call.
• voucher_info — Look up details about a voucher code without redeeming it. No auth required.
• redeem_voucher — Redeem a voucher code and bind it to your current MCP session.
• redeem_and_chat — Redeem a voucher and run your first chat call in one go.
• request_topup — Ask the admin who issued your voucher to add more budget.

Troubleshooting

401 invalid_key or no_key

Your Allotly key is missing, malformed, or revoked. Check the key starts with allotly_sk_ and is still active in your dashboard.

402 budget_exhausted

Your membership's budget is fully spent for this billing period. A Team admin can increase your budget; a voucher admin can add top-up credit.

403 account_suspended / account_expired

Your membership has been suspended by an admin or your access window has ended. Contact your team admin to reactivate.

429 rate_limit / concurrency_limit

You exceeded your tier's requests-per-minute or concurrent-request limits. Slow down your requests or upgrade your plan.

502/503 upstream errors

The underlying AI provider returned an error or timed out. Retry after a short delay. If the issue persists, check provider status pages.

MCP host fails on discovery / OAuth setup loop

The host can't reach our /.well-known/oauth-authorization-server endpoint. Confirm https://allotly.ai/mcp is reachable from your network and sync your machine's clock.