Add to <project>/.mcp.json:

Using uv (recommended):

{
  "mcpServers": {
    "codesurface": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/codesurface", "codesurface", "--project", "/path/to/your/src"]
    }
  }
}

Using pip install:

{
  "mcpServers": {
    "codesurface": {
      "command": "codesurface",
      "args": ["--project", "/path/to/your/src"]
    }
  }
}

Add to your project's CLAUDE.md so the AI knows when to use the tools:

## Codebase API Lookup (codesurface MCP)

Use the `codesurface` MCP tools to look up your project's classes, methods, properties, and fields instead of reading source files.

| When | Tool | Example |
|------|------|---------|
| Searching for an API by keyword | `search` | `search("MergeService")` |
| Need exact method signature | `get_signature` | `get_signature("TryMerge")` |
| Want all members on a class | `get_class` | `get_class("BlastBoardModel")` |
| Overview of indexed codebase | `get_stats` | `get_stats()` |
| After creating/deleting source files | `reindex` | `reindex()` |

codesurface/
├── src/codesurface/
│   ├── server.py           # MCP server — 5 tools
│   ├── db.py               # SQLite + FTS5 database layer
│   └── parsers/
│       ├── base.py         # BaseParser ABC
│       ├── csharp.py       # C# parser
│       ├── go.py           # Go parser
│       ├── java.py         # Java parser
│       ├── python_parser.py # Python parser
│       └── typescript.py   # TypeScript/TSX parser
├── pyproject.toml
└── README.md

"No codebase indexed"

• Ensure --project points to a directory containing supported source files (.cs, .go, .java, .py, .ts, .tsx)
• The server indexes at startup — check stderr for the "Indexed N records" message

Server won't start

• Check Python version: python --version (needs 3.10+)
• Check mcp[cli] is installed: pip install mcp[cli]

Stale results after editing source files

• Call reindex() — only re-parses files whose modification time changed, fast even on large codebases