codesurface — Claude Code MCP server: what it does, how to install
Extracts public APIs across your repository and serves signatures with line ranges so coding agents read fewer source tokens.
claude mcp add codesurface -- uvx codesurfaceWhat codesurface does
The server parses codebases during startup to catalogue exported classes, methods, and fields. It handles repositories in Go, Python, Java, C#, TypeScript, and C++ header files. This cuts token consumption. The assistant queries structured signatures instead of dumping entire source files.
Five tools manage the catalog: search, get_signature, get_class, get_stats, and reindex. The reindex tool checks file timestamps and runs automatically on query misses. Every result includes exact line ranges. This allows agents to read narrow line slices rather than thousands of implementation lines.
Running this server requires Python 3.10 or newer and the uvx CLI. Omitting the --project path argument leaves the server without files to index.
What it helps with
- retrieve method signatures without sending full source files into context
- inspect public members of a class with exact line positions
- perform targeted reads using line offsets instead of reading entire files
- refresh the API index incrementally based on modified file timestamps
Example prompts for the agent
- Search for the BlastBoardModel class using codesurface
- Get the exact signature for TryMerge
- Show codebase stats for the indexed files
How to install codesurface
Platform CLI
claude mcp add codesurface -- uvx codesurfaceuvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>
Platform CLI
codex mcp add codesurface -- uvx codesurfaceuvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>
Config file
{
"mcpServers": {
"codesurface": {
"command": "uvx",
"args": [
"codesurface"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>
Config file
{
"servers": {
"codesurface": {
"type": "stdio",
"command": "uvx",
"args": [
"codesurface"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>
Platform CLI
gemini mcp add codesurface uvx codesurfaceuvx runs the command named after the package; if the README names another one, use uvx --from codesurface <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about codesurface
How do I install codesurface in Claude Code?
Run claude mcp add codesurface -- uvx codesurface in your terminal. Pass --project followed by your source folder path to point the server to your code.
What does codesurface do?
It indexes public classes, functions, and properties across supported languages. AI assistants query these compact signatures and line numbers to avoid reading whole files.
Which programming languages does codesurface support?
The parser supports Python, Java, C#, Go, JavaScript, TypeScript, and C++ header files. Test files are excluded by default.
