{
  "markdown": "THIS REPO IS ARCHIVED AND THE SERVICE HAS BEEN SHUTDOWN\n\n# TokenOracle MCP\n\nToken Oracle is a Model Context Protocol (MCP) server that estimates, compares, and controls LLM API costs before agents spend tokens. It exposes nine tools, four read-only Resources, and a cost_analysis_workflow Prompt template. It uses a proprietary pricing algorithm without a backing LLM to ensure deterministic budget workflows. \n\n\nDesigned to work with agent swarms backing one or zero employee companies, Token Oracle acts as a tiny CFO within your OpenClaw swarm keeping spend down and making suggestions to improve promptings.\n\n\nSave them tokens, call Token Oracle today!\n\n**MCP tools exposed:**\n\n- `estimate_cost` — Estimates the USD cost of a single LLM API call before execution. Input: task_description, prompt_text, task_type, or explicit token_count. Output: cost_usd, recommended_model, confidence, will_fit_context, pricing_updated. Annotations: readOnlyHint:true, idempotentHint:true, openWorldHint:false.\n- `estimate_cost_batch` — Prices up to 100 LLM tasks in a single call. Returns per-task breakdown, total_cost_usd, and cheapest_model_for_all. Use before starting any multi-step pipeline.\n- `compare_models` — Ranks LLM pricing across all supported providers for a given task. Returns models sorted by cost with speed_tier and quality_tier. Supports filtering by min_quality, max_cost_usd, and provider. Input: task_type, token_count, or prompt_text.\n- `budget_check` — Checks whether a planned task fits within a monthly budget. Returns can_proceed (boolean), remaining_budget_usd, budget_consumed_pct, and cheaper_alternatives with savings_pct. Input: monthly_budget_usd, current_spend_usd, and task description.\n- `find_cheapest_for_budget` — Inverse of budget_check. Given a budget_usd cap and task, returns the best model/quality combination within budget plus all alternatives ranked by quality then cost.\n\n**MCP Resources exposed:**\n- `token-oracle://meta` — Machine-readable server capability document (version, model_count, pricing metadata)\n- `token-oracle://models` — Model IDs with metadata for discovery and validation\n- `token-oracle://heuristics` — Task-type token heuristics and keyword classifier patterns (auditable)\n- `token-oracle://pricing/changelog` — Append-only log of pricing changes; use to detect pricing updates over time\n\n**MCP Prompt exposed:**\n- `cost_analysis_workflow` — Guided three-step prompt template: estimate_cost → compare_models → budget_check. Arguments: task_description, monthly_budget_usd (optional), quality_threshold (optional).\n\n**Supported providers:** Anthropic, OpenAI, Google, Groq, Together AI, Mistral, DeepSeek, Cohere (100+ models).\n\n**Canonical agent workflow example:**\nGoal: Run 500 product description generation tasks. Budget $50/mo, current spend $43.\n1. estimate_cost_batch({ tasks: [{ task_type: \"generate\", token_count: { input: 200, output: 800 }, quantity: 500 }] }) → total_cost_usd: $0.60\n2. compare_models({ token_count: { input: 200, output: 800 }, task_type: \"generate\", min_quality: \"med\", max_cost_usd: 0.002 }) → deepseek-v3 at $0.00035/task ($0.175 total) — 71% cheaper, same quality tier\n3. budget_check({ monthly_budget_usd: 50, current_spend_usd: 43, token_count: { input: 200, output: 800 }, model: \"deepseek-v3\" }) → can_proceed: true, remaining: $6.825, budget_consumed_pct: 2.4%\nDecision: Use deepseek-v3. Save $0.425 vs gpt-4o-mini.\n\n**Pricing:**\n- Free: 1000 API calls/day, all hosted tools via the remote endpoint, no credit card\n- Pro ($29/mo): Unlimited calls, track_spend tool (persisted cost ledger per API key), priority throughput, spend attribution per agent/task/session\n\n**Contact:** info@guffeyholdings.com\n\n## Hosted endpoint\n\n- Canonical remote MCP URL: `https://mcp.guffeyholdings.com/TokenOracle`\n- Canonical MCP name: `com.guffeyholdings/token-oracle`\n\nDirect remote configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"token-oracle\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://mcp.guffeyholdings.com/TokenOracle\",\n      \"headers\": {\n        \"X-API-Key\": \"${TOKEN_ORACLE_API_KEY}\"\n      }\n    }\n  }\n}\n```\n\n## npm bridge package\n\nFor local clients that still expect an npm-installed stdio server, use `token-oracle-mcp`.\n\nZero-input trial flow:\n\nStart the bridge with no API key and, when the hosted service has trial auth enabled, it will automatically fetch and store a metered trial credential on first launch.\n\n```json\n{\n  \"mcpServers\": {\n    \"token-oracle\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"token-oracle-mcp\"]\n    }\n  }\n}\n```\n\nOne-time explicit login flow:\n\n```bash\nnpx -y token-oracle-mcp login\n```\n\nWith `--api-key`, that validates and stores a paid hosted API key. Without `--api-key`, it requests and stores a hosted trial credential instead. After either flow, the MCP config does not need to inject `TOKEN_ORACLE_API_KEY`.\n\n```json\n{\n  \"mcpServers\": {\n    \"token-oracle\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"token-oracle-mcp\"]\n    }\n  }\n}\n```\n\nIf you prefer stateless setup, keep passing `TOKEN_ORACLE_API_KEY` as an environment variable instead.\n\nHosted trial behavior:\n\n- Trial credentials are metered and capped server-side\n- Once the hosted trial request limit is reached, the service returns an upgrade-required response\n- The hosted service reuses the same still-valid trial credential for the same claimant instead of minting a fresh token each time\n- Trial issuance is separately throttled and can be blocked by server-side abuse risk scoring\n- Later, a hosted upgrade flow can replace the stored trial credential with a paid credential without changing MCP config\n\nOptional bridge environment variables:\n\n- `TOKEN_ORACLE_API_KEY`: optional hosted API key; overrides any stored credential\n- `TOKEN_ORACLE_BASE_URL`: override for the remote endpoint; defaults to `https://mcp.guffeyholdings.com/TokenOracle`\n- `TOKEN_ORACLE_SUBJECT`: optional end-user subject forwarded as `X-Token-Oracle-Subject`\n\nAdditional bridge commands:\n\n- `npx -y token-oracle-mcp login`: accept `--api-key` for paid auth, or fetch a hosted trial credential when no key is supplied\n- `npx -y token-oracle-mcp logout`: remove locally stored credentials\n\n## Capabilities\n\nTools:\n- `estimate_cost`\n- `estimate_cost_batch`\n- `compare_models`\n- `budget_check`\n- `find_cheapest_for_budget`\n- `get_budget_status`\n- `list_request_activity`\n- `get_usage_summary`\n- `get_usage_leaderboard`\n\nResources:\n- `token-oracle://meta`\n- `token-oracle://models`\n- `token-oracle://heuristics`\n- `token-oracle://pricing/changelog`\n\nPrompts:\n- `cost_analysis_workflow`\n\n## Versioning\n\n- Hosted service version: `1.0.6`\n- Bridge package version: `1.0.6`\n",
  "bytes": 6658,
  "sha": "f84b7d743c51fe2a7b6c110adac4aa599ed01eeb5079a010bc83e9529a76749e",
  "repo_slug": "victoryintech/tokenoracle-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_guffeyholdings_token_oracle_1975a49b/readme"
}