upfront MCP server
Commit Nov 10, 2026Analyzes token costs and tool compatibility for MCP servers, skills, and instruction files across various coding agents and clients.
Also known as thanatchon36/upfront
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is upfront MCP?
upfront analyzes token costs and tool compatibility for MCP servers, skills, and instruction files across various coding agents and clients.
Summary generated from the project's README
About upfront MCP server
Estimating the token cost of MCP servers and instruction files before interacting with a coding agent is what upfront enables. Developers can use this tool to see how much context their tool schemas, skills, and files like CLAUDE.md will consume across different environments. It works locally by parsing configuration files from your project or home directory and, with your permission, connecting to stdio, Streamable HTTP, or SSE servers to fetch real tool lists.
This utility provides compatibility checks for Claude Code, Codex, Gemini CLI, OpenCode, and Cursor. It identifies potential issues such as invalid OpenAI function names or Codex skill budget limits. By using the o200k_base tokenizer, it breaks down costs per server, per tool, and per instruction file. This helps prevent unexpected usage limits or broken tools before you begin a session.
What you can do with it
- 1Predict token consumptionCalculate how many tokens your MCP servers and instruction files will add to a prompt before you start typing.
- 2Verify tool compatibilityCheck if your tool names follow the specific naming rules required by OpenAI, Anthropic, or Gemini.
- 3Prevent Codex budget errorsEnsure your skills do not exceed the character limits that cause Codex to drop them.
- 4Automate cost auditing in CIIntegrate token budget checks into your continuous integration pipeline using JSON output and exit codes.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablethanatchon36/upfront is public and reachablegithub.com/thanatchon36/upfront ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/thanatchon36/upfront ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubupfront
See how many tokens your MCP servers, skills and instruction files cost a coding agent before you type a word, and which tools will break in Claude Code, Codex, Gemini CLI, OpenCode or Cursor.
The problem
"Claude Code sends 33k tokens before reading the prompt; OpenCode sends 7k" — Hacker News, 706 points; finding out took a logging proxy.
Every connected MCP server puts all of its tool schemas into the context, every skill adds its
description, and AGENTS.md / CLAUDE.md ride along on every request. Usage limits arrive early,
and Codex starts dropping skills (codex#19679)
and MCP tools (codex#44308) once budgets run
out. Claude Code's /context shows this for Claude Code only; OpenCode closed the request as
not planned.
Demo

$ uv run upfront examples/demo --yes --top 2 # in a clone of this repository
upfront 0.1.0 · examples/demo · tokens o200k_base
claude-code ≈ 6,786 before your first prompt
mcp filesystem (14 tools, project) ≈ 2,751 41% of total
read_media_file ≈ 285
read_text_file ≈ 251
mcp memory (9 tools, project) ≈ 2,365 35% of total
create_entities ≈ 349
search_nodes ≈ 320
mcp everything (13 tools, project) ≈ 1,602 24% of total
gzip-file-as-resource ≈ 239
get-structured-content ≈ 186
skills (2, name + description) ≈ 33 bodies ≈ 48 load on demand
CLAUDE.md ≈ 35
...
compatibility
error codex issue-scenarios.files.read: 'files.read' (10 chars) is not a valid OpenAI function name
[openai-tool-name] https://github.com/openai/openai-python/blob/main/src/openai/types/shared_params/function_definition.py
The demo's servers replay tools/list snapshots of the official
filesystem, memory and everything reference
servers (1.0.0), so the numbers above are what those servers really cost.
Install
uvx upfront # run from your project, no install
pip install upfront
Python 3.11+. Then, in a project:
upfront # skills, instruction files and the list of servers; starts nothing
upfront --yes # also start/connect to each MCP server and count its tools
Features
- Five harnesses, both scopes. Reads Claude Code, Codex, Gemini CLI, OpenCode and Cursor configs from the project and your home directory, including
${VAR:-default}expansion and JSONC. - Real tool lists. Talks to every stdio, Streamable HTTP and SSE server with the official MCP SDK, follows pagination, and reports failures (missing command, timeout, "auth required") per server instead of crashing.
- Where the tokens go. Per server and per tool, skill metadata separately from skill bodies, and every instruction file.
- Compatibility checks with sources. Tool names against OpenAI, Anthropic and Gemini rules,
$refparameters in Claude Code, non-standard formats in OpenCode, and Codex's skills budget. Every finding links the documentation or open issue it comes from. - CI-friendly.
--json,--budget Nand--strictexit codes, and--tools-fileto check a savedtools/listwithout starting anything. - Safe by default. Nothing is launched without consent: it asks in a terminal and needs
--yeselsewhere. It only ever callstools/list.
How it compares
| upfront | Claude Code /context |
mcp-assert | ccusage | |
|---|---|---|---|---|
| Up-front cost of MCP tools, skills, instruction files | yes, per harness | yes, Claude Code only | no | no |
| Works for Codex, Gemini CLI, OpenCode | yes | no | n/a | n/a |
| Per-client schema compatibility | yes, 6 sourced rules | no | no; 24 usability lint rules (descriptions, nesting) | no |
| Tests tool behaviour | no | no | yes (assertions, fuzzing) | no |
| Actual spend from past sessions | no | /usage |
no | yes |
Use /context inside Claude Code, mcp-assert to test what your tools do, and
ccusage to see what you've already spent. upfront answers "what will each agent load, and what
breaks where" before you start.
How it works
- Discover: parse each harness's documented config files (concepts).
- Fetch: with consent, start each distinct server once (from the project directory, like the agent) and page through
tools/list. - Count: tokenize each tool's wire JSON with
o200k_base; skill metadata and bodies separately; instruction files whole. - Check: run the per-client rules (table).
More: quickstart · concepts · FAQ · API · decisions
Limitations
- Estimates. One tokenizer for every model; vendors' counts differ, and clients add their own framing around tools (ADR-0003).
- Not the vendor's system prompt. Only what you add is measured.
- Lazy loading isn't modelled. Claude Code's tool search and OpenCode's lazy MCP loading defer some definitions; upfront reports their full cost.
- No OAuth. Remote servers that need a login show "auth required; not measured". Headers from your config are sent; OAuth flows are not run.
- Root-level instruction files only; Cursor currently contributes MCP server configurations only.
- Codex's 2% skills budget depends on the model's window; upfront checks the documented 8,000-character fallback.
Roadmap
- v0.2: exact counts via vendor token-count APIs (opt-in), a
--fixproxy that rewrites schemas per client, and Windsurf configs. - v0.3:
upfront diffbetween git refs for MCP server pull requests, and a GitHub Action.
Contributing
Bug reports with a config that reproduces the problem help most. See CONTRIBUTING.md; compatibility rules need a public source.
License
upfront MCP questions
What does upfront measure?
It calculates the token cost of your MCP servers, skills, and instruction files before you start a session, and checks for tool compatibility issues.
Does it support OAuth?
No, it does not support OAuth flows. Remote servers requiring login will be reported as 'auth required; not measured'.
How does it handle different tokenizers?
It uses a single tokenizer (o200k_base) for all models, which means estimates may differ from actual vendor counts.
Is it safe to run?
Yes, it is safe by default and only calls the tools/list method without launching anything unless you provide consent.