Papers are excluded before ranking¶
The `node_types` parameter on `search_entities` is independent of the
same parameter on `bfs_query`. The former restricts which entity types
are returned by the search; the latter controls which entity types
receive full metadata in a traversal. Both are optional. Both exist to
help the LLM manage an otherwise ambiguous result set.
## Chapter 7: MCP as the Delivery Mechanism
In 2024, Anthropic introduced the Model Context Protocol -- MCP -- as a
standard for connecting language models to external tools and data
sources. The timing was not
accidental. By 2024, the pattern of equipping LLMs with tools -- functions
the model could call, results it could reason over -- had become standard
practice, but the implementations were fragmented. Every tool integration
was bespoke: a custom function signature, a custom serialization format,
a custom connection mechanism. Integrating a new tool into a new model
meant writing new code for every combination.
MCP's value proposition was standardization. A tool implemented to the
MCP specification could be connected to any MCP-compatible client without
modification. The tool vendor didn't need to know which model would call
it. The model vendor didn't need to know which tools would be connected.
The protocol was the contract between them.
This is the same insight that made HTTP successful as a substrate for the
web, and that made USB successful as a hardware interface standard: an
agreed protocol, implemented by many parties independently, creates a
market of interoperable components. The value grows with the number of
implementations.
BFS-QL is implemented as an MCP server. This choice determines how graphs
are connected to models, how the connection is configured, and what the
operational model looks like.
### The Connection Model
Connecting a BFS-QL graph to an MCP-compatible LLM client takes three
steps:
**Provision.** Start the BFS-QL server against a backend:
```bash
uv run bfs-ql serve --backend postgres --transport sse \
--description "My knowledge graph"
Register. Tell the client where the server is:
Connect. Start a new session. The client connects to the server, receives the tool definitions and server instructions, and the six BFS-QL tools are available immediately.
That is the complete setup. No schema configuration, no query templates,
no prompt engineering. The graph self-describes through describe_schema;
the server instructions carry graph-specific guidance; the tools define
their own parameters and return types. The LLM needs no external
documentation to use the interface.
This is the self-description principle from Chapter 5 extended to the connection layer. Not just the schema -- the entire interface is self-contained.
SSE and Stdio¶
MCP supports multiple transport mechanisms. BFS-QL supports two:
SSE (Server-Sent Events) runs the BFS-QL server as a persistent HTTP
service. The client connects over HTTP; the server pushes responses as
events. SSE is the right choice for most deployments: it supports multiple
concurrent clients, runs as a background service, and is accessible from
any MCP client on the network. The URL format (http://host:port/sse) is
what gets registered with the client.
Stdio runs the BFS-QL server as a subprocess. The client spawns the server process and communicates over standard input and output. Stdio is the right choice for environments where network access is restricted or where the graph server should not persist between sessions. It is the default transport and requires no port configuration.
For local development against the medlit demo dataset, SSE is more convenient -- the server starts once and remains available across sessions. For production deployments, SSE also simplifies monitoring and restart management.
The Protocol as Active Contract¶
It is worth being precise about what MCP provides and what it does not.
MCP is a transport and discovery protocol. It specifies how tools are described (JSON Schema), how they are called (JSON-RPC), and how results are returned. It does not specify what the tools do, what data they return, or how the LLM should use them. Those are determined by the tool implementation -- in this case, by BFS-QL.
The distinction matters because it clarifies where the intelligence lives. MCP connects the model to the server. BFS-QL determines what the server can do and how it behaves. The model decides how to use it.
This is the right division of labor. MCP handles the plumbing. BFS-QL handles the graph interface semantics: stubs versus full nodes, topology completeness, the working set model, canonical IDs as seeds. The model handles the reasoning: what to query, what the results mean, what to do with them.
None of these three components knows more than it needs to about the others. The model doesn't know whether the backend is Postgres or SPARQL or Neo4j -- it only sees six tools. BFS-QL doesn't know what question the model is trying to answer -- it only executes queries. The backend doesn't know anything about either -- it only answers eight primitive operations. Each layer is replaceable independently of the others.
This composability is not an accident of the implementation. It is the
consequence of having a well-defined protocol at each boundary. MCP defines
the boundary between model and server. The GraphDbInterface ABC defines
the boundary between server and backend. The BFS-QL query format defines
the boundary between the model's intent and the traversal engine. Clean
boundaries make components replaceable. Replaceable components make the
system adaptable to backends and clients that do not yet exist.
The graph a hospital runs today against its clinical knowledge base is, from the model's perspective, indistinguishable from the graph a pharmaceutical company runs against its compound library, or the graph a university runs against its research literature. Same six tools. Same query format. Same session workflow. The MCP protocol is how that uniformity is delivered.