lessons from building an MCP server for codebase context (ranking is the hard part)

i've been working on an MCP server that gives coding agents repo context - semantic + structural (AST) + dependency-graph + text search behind a handful of tools. sharing a few things that weren't obvious going in, curious how others building MCP servers have handled the same.

1. the retrieval is easy, the ranking is the whole game. returning 40 matches is worse than returning the 3 an agent should read first. recall@1 matters more than total results when there's a token budget and an agent on a clock. we ended up ranking symbols by graph centrality (pagerank-ish) so the most-depended-on thing surfaces first.

2. one modality isn't enough. semantic search alone misses exact-string cases; grep alone misses "i know the behavior, not the name"; neither gives you callers/dependents. fusing them into one ranked surface beat any single lens in our own eval.

3. tool design > tool count. agents pick the wrong tool when the descriptions overlap. tighter, non-overlapping tool boundaries fixed more failures than adding tools did.

4. citations change agent behavior. returning file:line with every result made downstream agents stop guessing paths, because they could verify before editing.

disclosure so i'm not sneaky about it: i help build one of these (maguyva). not linking it - this is more that i want to compare notes, especially on ranking and on transport choices (stdio vs streamable http) for remote servers. what's worked for the rest of you?