How I Found a Silent API Bug in a 3,548-Star MCP Server

Eshaan Agrawal — Mon, 29 Jun 2026 05:44:47 +0000

How I Found a Silent API Bug in a 3,548-Star MCP Server

The API accepted your request. Returned HTTP 200. And then quietly did nothing.

No error. No stack trace. Just an empty result where your Cypher query should have run.

This is the story of how I found that bug in CodeGraphContext — an MCP server that indexes local codebases into a graph database to give AI assistants real code context. 3,548 stars. Actively maintained. Used by developers building on top of Claude and other LLM toolchains.

And it had a silent failure sitting in its public HTTP query endpoint.

What is CodeGraphContext?

Before the bug — quick context.

CodeGraphContext is an MCP (Model Context Protocol) server. It lets you point it at a codebase, index it into a graph database (FalkorDB or Kuzu), and then query that graph using Cypher — the query language for graph databases. The idea is that AI assistants can use it to understand code structure, dependencies, and relationships at a depth that flat file reads don't give you.

It exposes both an MCP interface and a standard HTTP API. The HTTP API is what's relevant here.

How I Found It

I wasn't hunting for bugs. I was reading the source.

When I contribute to a new repo, I start by tracing a single request end-to-end through the codebase. Pick an endpoint, follow it from the route definition into the handler, into any downstream calls, and back out. It's the fastest way to actually understand what a codebase does.

I started with /api/v1/query — the endpoint that lets you send a Cypher query over HTTP and get results back.

The route lives in src/codegraphcontext/api/router.py. Here's what I found at line 89:

server.handle_tool_call("execute_cypher_query", {
    "query": request.query,
    "params": request.params
})

The route was calling handle_tool_call with the tool name execute_cypher_query and passing the query as "query".

Then I went to the handler. src/codegraphcontext/tools/handlers/query_handlers.py, line 16:

cypher_query = args.get("cypher_query")
if not cypher_query:
    return {"error": "Cypher query cannot be empty."}

The handler reads cypher_query. Not query. cypher_query.

The route passes query. The handler reads cypher_query. They never meet.

So args.get("cypher_query") returns None. The handler hits the empty check. Returns {"error": "Cypher query cannot be empty."}. HTTP 200.

A valid request, carrying a real Cypher query, silently failed — not because the query was wrong, but because the key name didn't match across an internal function call boundary.

Why This Is Easy to Miss

The failure mode is the problem.

If this threw an exception, you'd see a 500. If it returned a 4xx, you'd know the API rejected your input. But it returned 200 with an error payload that looks like a validation error. The natural read is: "I sent a bad query." The actual problem is: the API layer and the tool handler were speaking different languages about what to call the same field.

Here's the repro from the issue I filed:

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{"query":"MATCH (n) RETURN count(n) AS count","params":{}}'

Valid Cypher. Valid JSON. Valid HTTP request. But the tool handler sees no cypher_query key — because the route called it query — and returns empty.

The request body looks correct at the API boundary. The failure happens after the internal translation. That's what makes it a confusing debugging path. You'd inspect the request, see a valid payload, and have no obvious reason to look at the key name being passed between the route and the handler.

The Fix

One line change in router.py:

# Before
server.handle_tool_call("execute_cypher_query", {
    "query": request.query,
    "params": request.params
})

# After
server.handle_tool_call("execute_cypher_query", {
    "cypher_query": request.query,
    "params": request.params
})

Change the key from "query" to "cypher_query" so it matches what the handler expects.

I kept the fix narrow — just aligning the key name, no refactoring, no schema changes. Then added a regression test in tests/unit/api/test_query_router.py that verifies a POST to /api/v1/query reaches execute_cypher_query with the correct key. So this can't silently break again.

What I Added: The Regression Test

This is the part I'd push anyone fixing a bug like this to do.

The fix itself is obvious once you see it. What's not obvious is that without a test, the exact same mismatch can come back — someone refactors the handler to read a different key, or the route gets updated without checking what the handler expects, and you're back to square one.

The test mocks server.handle_tool_call and asserts that after a valid POST to /api/v1/query, the mock is called with "cypher_query" in the arguments dict. Small test, precise assertion, catches exactly this class of regression.

def test_query_route_passes_cypher_query_key(client, mock_server):
    response = client.post(
        "/api/v1/query",
        json={"query": "MATCH (n) RETURN count(n)", "params": {}}
    )
    call_args = mock_server.handle_tool_call.call_args
    assert "cypher_query" in call_args[0][1]

The Broader Pattern

This is a specific instance of a bug pattern that shows up everywhere in layered systems: argument name drift.

You have a public interface (the HTTP route) that translates external input into an internal call. The public interface uses one name (query). The internal interface expects another (cypher_query). Both sides are internally consistent. The mismatch only exists at the translation boundary — and unless someone traces the full call path, it's invisible.

It's especially common when:

An internal tool or handler is defined separately from the route that calls it
The field names are semantically similar but not identical (query vs cypher_query)
The failure mode is a validation error rather than an exception (so it looks like bad input, not a broken translation)

The fix is always the same: trace the call, align the names, add a test that pins the contract.

What's Next

I also filed and opened PR #1026 on the same repo — the MCP SSE module was importing mcp.server and mcp.server.sse without declaring mcp as a runtime dependency in pyproject.toml. Clean installs could fail at import time with a ModuleNotFoundError on a code path the project advertises. That one's a writeup for another day.

If you're building on MCP or contributing to open source Python projects — read the source end-to-end before you start. One pass through a real request flow teaches you more about a codebase than reading the README three times.

This fix was part of my GSSoC 2026 contributions. I'm currently ranked #50 globally (S Tier, top 1% of 43,587 contributors) across 14 repos. Writing about the bugs that actually taught me something.

DEV Community: Eshaan Agrawal

How I Found a Silent API Bug in a 3,548-Star MCP Server

How I Found a Silent API Bug in a 3,548-Star MCP Server

What is CodeGraphContext?

How I Found It

Why This Is Easy to Miss

The Fix

What I Added: The Regression Test

The Broader Pattern

Links

What's Next