Serve the semantic layer over MCP

Unos 26 minutos de lectura, con 5 ejemplos en 7 secciones.

Edición 2026.11.15 Ejemplos verificados el 19 de nov de 2026 78 de 78 ejemplos pasan Qué ha cambiado

Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros

Traducido del libro en inglés, edición 2026.11.15. Lee el original

Esta parte aún no está traducida, así que está en inglés.

By the end of this chapter, you can serve the shop's governed metrics as MCP tools that answer for the role the server was built for, return each answer with its provenance as structured data, test the server in memory, and run the book's agent through it as a host.

The shop's teams ask their questions from the assistant each person already uses, but the agent so far lives inside the book's Python: chapter 6 gave it five metric tools over the semantic layer, and chapter 9 put each role's row filters, column masks and minimum group size underneath them, in lib/policies.py. People in the shop don't work inside that Python. Each assistant, a chat app on a desktop or an editor with an agent built in, could get its own copy of the tools, and then each copy would need its own copy of the access rules, kept in step by hand. The first copy that drifts gives a regional lead another region's revenue.

The Model Context Protocol (MCP) removes the copies. MCP is an open protocol in which an application, the host, runs a client for each server it connects to, and a server offers tools that the host's model can call. Model Context Protocol in Practice covers the protocol, from host, client and server to authorization. Here, the shop's semantic layer becomes one MCP server, which this chapter calls the semantic server, in lib/semantic_server.py. It offers the same five tools as the in-process agent, through chapter 9's PolicyToolbox, the metric tools with the role's access rules underneath, so every host that connects gets the same metrics and the same rules. The examples use the Python software development kit for MCP, mcp 2.3.0, which speaks the specification's revision 2026-07-28, and every one of them runs in memory, with no port and no process.

Convierte métricas en herramientas

Último cambio en la edición 2026.11.12

Una herramienta MCP es un nombre, una descripción que el modelo lee, un JSON Schema para sus argumentos y, opcionalmente, un esquema para su resultado. Un cliente descubre las herramientas de un servidor con tools/list y llama a una con tools/call. La especificación indica que la lista no debe variar por conexión, aunque sí puede variar según la autorización presentada en la solicitud, y que los servidores deberían devolver las herramientas en un orden determinista (tools). Por lo tanto, las preguntas para una capa semántica son qué herramientas ofrecer y si un rol debe ver menos de ellas.

Recomendamos ofrecer las herramientas que el agente ya tiene. El capítulo 6 eligió cinco para el agente de la tienda: list_metrics, describe_metric, query_metric, ask_back y cannot_answer. Se midieron con las preguntas de referencia, cuyas respuestas se comprobaron ejecutándolas, y piden al modelo que elija una solicitud de métrica, nunca que escriba SQL. build_server() en lib/semantic_server.py registra una herramienta MCP para cada una, con una descripción que el modelo lee y argumentos tipados, y el cuerpo de cada herramienta llama al mismo método de PolicyToolbox del capítulo 9 que llama el agente en proceso. Las herramientas se registran por orden de nombre. Cada una se marca como de solo lectura, idempotente y de mundo cerrado con las anotaciones de herramienta de MCP. Model Context Protocol in Practice explica cómo escribir descripciones que el modelo lee y por qué las anotaciones son sugerencias, no garantías.

Lo que cambia según el rol se ve mejor lado a lado: un servidor para el analista, que lo ve todo, y otro para el equipo de soporte, que puede no ver los ingresos. El código lista las herramientas de cada servidor y compara su catálogo list_metrics con el que el agente en proceso incluye en su prompt.

list-metric-tools.py Python 3.12.15 · anyio 4.16.0 · duckdb 2.0.0 · mcp 2.3.0 · pydantic 2.14.3 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""The semantic layer as an MCP server: the tools it lists, what query_metric takes, and each role's catalog.The `support, metrics` line settles that support's catalog holds no revenue metric, and the `same catalog as thein-process agent` lines settle that each catalog is the prompt's own text."""import anyiofrom mcp import Clientfrom lib.metric_tools import catalogfrom lib.policies import PolicyLayer, policy_forfrom lib.semantic import loadfrom lib.semantic_server import build_serverfrom lib.warehouse import connectcon, layer = connect(), load()async def main():    listed = {}    for role in ("analyst", "support"):        async with Client(build_server(role, shop=con, layer=layer)) as client:   # in memory: no port, no process            tools = (await client.list_tools()).tools            text = (await client.call_tool("list_metrics", {})).structured_content["text"]        listed[role] = [t.name for t in tools]        metrics = [line[2:].split(":")[0] for line in text.splitlines()]   # catalog lines start with "- ", then the name        print(f"{role}, tools: {', '.join(listed[role])}")        print(f"{role}, metrics in list_metrics: {len(metrics)}")        print(f"{role}, metrics: {', '.join(metrics)}")        in_process = catalog(PolicyLayer(layer, policy_for(role), con))        same = text == in_process                  # PolicyLayer builds the in-process prompt's catalog, so MCP must match it        assert same        print(f"{role}, same catalog as the in-process agent: {'yes' if same else 'no'}")    query = next(t for t in tools if t.name == "query_metric")    print(f"query_metric inputs: {', '.join(query.input_schema['properties'])}")    print(f"query_metric requires: {', '.join(query.input_schema['required'])}")    print(f"tools marked read-only: {sum(t.annotations.read_only_hint for t in tools)} of {len(tools)}")    print(f"tools with a role input: {sum('role' in t.input_schema['properties'] for t in tools)}")    print(f"same tool list for both roles: {listed['analyst'] == listed['support']}")anyio.run(main)
Salidapython list-metric-tools.py
analyst, tools: ask_back, cannot_answer, describe_metric, list_metrics, query_metric
analyst, metrics in list_metrics: 10
analyst, metrics: net_revenue, gross_revenue, orders, line_net_revenue, units_sold, refunds, order_refunds, new_customers, refund_rate, average_order_value
analyst, same catalog as the in-process agent: yes
support, tools: ask_back, cannot_answer, describe_metric, list_metrics, query_metric
support, metrics in list_metrics: 5
support, metrics: orders, units_sold, refunds, order_refunds, new_customers
support, same catalog as the in-process agent: yes
query_metric inputs: metrics, group_by, filters, order_by, limit
query_metric requires: metrics
tools marked read-only: 5 of 5
tools with a role input: 0
same tool list for both roles: True

Ambos servidores listan las mismas herramientas: ask_back, cannot_answer, describe_metric, list_metrics, query_metric. Lo que difiere es el catálogo. El list_metrics del analista devuelve 10 métricas y el de soporte 5: orders, units_sold, refunds, order_refunds, new_customers. Todas las métricas de ingresos desaparecen del catálogo de soporte, porque el PolicyLayer del capítulo 9 oculta cualquier métrica que lea una columna a la que su rol no tiene acceso. Para ambos roles, el catálogo sobre MCP es el mismo texto que el agente en proceso incluye en su prompt. Eso importa para el host: un catálogo sin cambios implica un prompt sin cambios.

query_metric recibe metrics, group_by, filters, order_by, limit y solo requiere metrics. De las herramientas del servidor, 5 of 5 están marcadas como de solo lectura, y 0 reciben un argumento llamado role, que es el tema de la siguiente sección.

Mantener una sola lista de herramientas para todos los roles fue una decisión. La especificación permitiría que el servidor de soporte listara menos herramientas, pero cada una de las cinco es útil para todos los roles, y el rol cambia lo que devuelve una herramienta, no si existe. El caso para acortar la lista es un rol que no puede usar una herramienta en absoluto, y Model Context Protocol in Practice trata limitar las herramientas según lo que permite el token. El costo de una lista larga es el tema de mantener pequeña la lista de herramientas del mismo libro.

Regla práctica: Sirve las herramientas con las que se midió tu agente, cada una como una llamada ligera al mismo código que usa el agente en proceso, para que el servidor no se desvíe de lo que probaste. Enuméralas en un orden fijo y márcalas como de solo lectura. Deja que el rol cambie lo que devuelve una herramienta, y acorta la lista de herramientas solo cuando un rol no pueda usar una herramienta en absoluto.

Esta parte aún no está traducida, así que está en inglés.

Carry the caller's role into every query

Último cambio en la edición 2026.11.15

A server that enforces chapter 9's access rules has to know whose rules to enforce, and that's the part an MCP server most often gets wrong. Revision 2026-07-28 has no protocol-level sessions: it removed the initialize handshake and the Mcp-Session-Id header, so every request stands alone (changelog). There's no session to hold a role. The specification gives two places for identity instead. A server that a host launches over stdio, for one person, "SHOULD NOT" use MCP's authorization and should take credentials from the environment (authorization). A server on HTTP derives the user from a verified access token: the specification's security guidance, on binding a server's state to a user, derives the user ID from the verified token, not from anything the client supplies (security best practices).

The tempting third place is a tool argument: give query_metric a role parameter and let the host fill it in. Then the role is whatever the caller sends, and the caller is a model that reads questions and, as chapter 9 showed, text inside the data. Three servers answer one request. Each receives gq-017, net revenue in each of "our countries" in 2025, asked by EMEA's regional lead, with "role": "analyst" added to the arguments. The first server takes the role as an argument. The second is the semantic server, built for EMEA's lead with build_server("regional_lead", "EMEA"). The third is built by server_from_environment(), which reads SHOP_ROLE and SHOP_REGION as a host would set them when it launches the server for one person. Last, the request runs once more on that third server's database, through the plain semantic layer with no policy, as the paragraph after the results explains.

role-bound-at-build.py Python 3.12.15 · anyio 4.16.0 · duckdb 2.0.0 · mcp 2.3.0 · pydantic 2.14.3 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""gq-017 from EMEA's regional lead, sent with role "analyst": a server that takes the role as an argument obeys it,and one that binds the role when it is built ignores it, and queries a database that holds only the lead's rows.The `role as argument, countries` line shows every country a request-supplied role returns, and the `role bound atbuild, countries` line settles that a server built for the lead returns EMEA's countries only."""import anyiofrom mcp import Clientfrom mcp.server.mcpserver import MCPServerfrom lib.policies import PolicyLayer, PolicyToolbox, policy_forfrom lib.semantic import MetricRequest, loadfrom lib.semantic_server import build_server, server_from_environmentfrom lib.warehouse import connectcon, layer = connect(), load()naive = MCPServer("role-as-argument")@naive.tool()def query_metric(metrics: list[str], group_by: list[str] = [], filters: dict = {}, role: str = "analyst",                 region: str | None = None) -> list[list]:    """The anti-pattern: whoever calls the tool says who they are, and it queries the whole warehouse."""    toolbox = PolicyToolbox(con, PolicyLayer(layer, policy_for(role, region), con))    return [list(row) for row in toolbox.query_metric({"metrics": metrics, "group_by": group_by,                                                       "filters": filters}).answer.rows]request = {"metrics": ["net_revenue"], "group_by": ["order__country"], "filters": {"metric_time__year": 2025},           "role": "analyst"}                     # the lead's request, with a role the lead doesn't haveenvironment = {"SHOP_ROLE": "regional_lead", "SHOP_REGION": "EMEA"}   # what a host sets for a stdio serverasync def main():    servers = {"role as argument": naive, "role bound at build": build_server("regional_lead", "EMEA", con, layer),               "role from the environment": (stdio := server_from_environment(environment, con))}    for name, server in servers.items():        async with Client(server) as client:            result = (await client.call_tool("query_metric", request)).structured_content        rows = result["result"] if "result" in result else result["answer"]["rows"]        print(f"{name}, countries: {', '.join(row[0] for row in rows)}")        if "answer" in result:            provenance = result["answer"]["provenance"]            print(f"{name}, provenance: role {provenance['role']}, row filter {provenance['filters']['row filter']}")    # The policy bypassed: the plain semantic layer, which applies no role, on the stdio server's own database.    bypass = layer.query(stdio.database, MetricRequest.from_arguments({k: v for k, v in request.items() if k != "role"}))    print(f"role from the environment, no policy, countries: {', '.join(row[0] for row in bypass.rows)}")anyio.run(main)
Salidapython role-bound-at-build.py
role as argument, countries: AU, CA, DE, ES, FR, GB, JP, NL, SG, US
role bound at build, countries: DE, ES, FR, GB, NL
role bound at build, provenance: role regional_lead, row filter EMEA only
role from the environment, countries: DE, ES, FR, GB, NL
role from the environment, provenance: role regional_lead, row filter EMEA only
role from the environment, no policy, countries: DE, ES, FR, GB, NL

The server that takes the role as an argument returned AU, CA, DE, ES, FR, GB, JP, NL, SG, US: every country in the shop, because the request said "analyst" and the server believed it. The semantic server returned DE, ES, FR, GB, NL, EMEA's countries only, and its provenance says why: role regional_lead, row filter EMEA only. Its tools have no role parameter, so the extra argument went nowhere: the SDK validated the arguments against each tool's parameters, dropped the one it didn't know, and ran the call. The server built from the environment returned DE, ES, FR, GB, NL. Binding the role at build means one server per person, which is what stdio gives you: the host starts a process for its user, and the process lives as long as the host needs it (Choose stdio or Streamable HTTP).

The binding decides two things, and the database is the first. The book's primary access control is what the database allows each role: a read-only connection to that role's own views, which hold only its rows and columns, as chapter 7 built it, with chapter 9's policy rewrite as a second layer behind it. So build_server() doesn't take a connection to query. It takes the shop's warehouse, derives the role's policy, and opens the role's own database with agent_warehouse(shop, policy=policy, semantic=SEMANTIC_TABLES): chapter 7's database, plus the semantic layer's views and calendar as the role sees them, so that metrics can run on it. Every tool queries that database, and no caller can pair a role with another role's. The final step runs the lead's request through the plain semantic layer, which applies no role, on the environment server's own database. It returned DE, ES, FR, GB, NL: with the policy bypassed, there are still only EMEA's rows to read.

The second is what counts as forbidden, which the policy alone decides: a filter on region with any value but the lead's own is forbidden. Any other value the lead's rows don't hold, such as another region's country, gets a correctable error listing the lead's own values, whether it exists elsewhere or not, so it reveals nothing (chapter 9).

A server on HTTP serves many people, so it can't bind a role when it starts. It needs the role on each request, from the token. In the Python SDK, the server is given a TokenVerifier whose verify_token() returns an AccessToken with the client's ID, its scopes and the token's claims, and a tool reads the verified token with get_access_token() (mcp/server/auth/provider.py, mcp/server/auth/middleware/auth_context.py). The server would map a claim to a role and region there, and choose that role's database and policy for the call. The token must have been issued for this server: servers must check that each access token was issued for them, as its intended audience (authorization), which Model Context Protocol in Practice builds in bind each token to one server. Scopes don't replace the access rules. A scope can say that a token may call query_metric; only the database and the policy can say which rows it reads, and the specification's security guidance lists trusting the scopes a token claims, with no server-side check, as a common mistake (security best practices). Nothing here runs this path, because an in-memory client has no HTTP layer, so no bearer token reaches the server, and get_access_token() returns None there.

Working rule: Bind the role where the person was authenticated, never in a tool's arguments. For a stdio server, the host passes the role in the environment, and the server opens that role's read-only database and builds its policy once. For an HTTP server, take the role from a verified token issued for this server, on every request, and enforce the role's rows in the database and the policy whatever the token's scopes say. Leave role out of every input schema, so there's nothing for a model or a question to fill in, and log any argument a tool ignores, role first, because one is a sign that text the model read is steering it (treat ticket text as untrusted data).

Esta parte aún no está traducida, así que está en inglés.

Return answers with their provenance

Último cambio en la edición 2026.11.15

With the role bound, the server's answers are right for the person asking. The host still has to know what each answer is: which metric produced it, with which filters, for which role and from data how fresh. Chapter 1 called that an answer's provenance, and the in-process agent keeps it in Answer.provenance. Over MCP, a tool can declare an outputSchema and return structuredContent that conforms to it, and a tool that does "SHOULD also return the serialized JSON in a TextContent block" (tools). Structured content is what lets a host's code, rather than its model, read an answer's role and filters. Model Context Protocol in Practice shows how the SDK builds the schema from a return type in return structured content with an output schema.

Every tool of the semantic server returns a ToolReply, a pydantic model with two fields: text, the text the in-process tool shows the model, and answer, the answer with its rows and provenance, or nothing when the result doesn't end the run. Failures take two routes. The MCP specification reports a tool execution error as a result with isError set, with "actionable feedback that language models can use to self-correct" (tools). A request with a misspelt dimension is that kind of failure, so the server raises the SDK's ToolError with chapter 6's validation message. A request the role may not make isn't, and the server returns it as an answer that declines, with a reason that starts "forbidden", as PolicyToolbox does in process. Each route is worth seeing from the host's side: the finance team's refund rate by region for fiscal 2026, the same with order_region for order__region, and the support team's net revenue for 2025.

tool-result-with-provenance.py Python 3.12.15 · anyio 4.16.0 · duckdb 2.0.0 · mcp 2.3.0 · pydantic 2.14.3 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""What a host receives from query_metric: an answer with its provenance as structured content, a request the modelcan correct as a tool error, and a request the role may not make as an answer that declines. The `text block is the same JSON: yes` line settles thatthe finance answer's text matches its structured content, and `support, net revenue` with `is_error: False` and`answered: no` settles that a forbidden request declines rather than errors."""import jsonimport anyiofrom mcp import Clientfrom lib.semantic import loadfrom lib.semantic_server import build_serverfrom lib.warehouse import connectcon, layer = connect(), load()asks = {"finance, refund rate": ("finance", {"metrics": ["refund_rate"], "group_by": ["order__region"],                                             "filters": {"metric_time__fiscal_year": 2026}}),        "finance, misspelt dimension": ("finance", {"metrics": ["refund_rate"], "group_by": ["order_region"]}),        "support, net revenue": ("support", {"metrics": ["net_revenue"], "filters": {"metric_time__year": 2025}})}async def main():    for name, (role, request) in asks.items():        async with Client(build_server(role, shop=con, layer=layer)) as client:            tool = next(t for t in (await client.list_tools()).tools if t.name == "query_metric")            result = await client.call_tool("query_metric", request)        print(f"{name}, is_error: {result.is_error}")        if result.is_error:            print(f"{name}, text: {result.content[0].text}")            continue        answer = result.structured_content["answer"]        answered = answer["answered"]        assert answered == (role != "support")   # support may see no revenue, so its answer declines        print(f"{name}, answered: {'yes' if answered else 'no'}")        same = json.loads(result.content[0].text) == result.structured_content   # the specification asks for this JSON in the text block        assert same        print(f"{name}, text block is the same JSON: {'yes' if same else 'no'}")        if answer["answered"]:            print(f"{name}, rows: {', '.join(f'{region} {rate:.2%}' for region, rate in answer['rows'])}")            print(f"{name}, provenance fields: {', '.join(answer['provenance'])}")            print(f"{name}, provenance: {json.dumps({k: v for k, v in answer['provenance'].items() if k != 'sql'})}")        else:            print(f"{name}, reason: {answer['reason']}")    print(f"output schema requires: {', '.join(tool.output_schema['required'])}")anyio.run(main)
Salidapython tool-result-with-provenance.py
finance, refund rate, is_error: False
finance, refund rate, answered: yes
finance, refund rate, text block is the same JSON: yes
finance, refund rate, rows: AMER 7.11%, APAC 6.02%, EMEA 8.45%
finance, refund rate, provenance fields: source, metric, sql, filters, role, data_as_of
finance, refund rate, provenance: {"source": "metric", "metric": "refund_rate", "filters": {"metric_time__fiscal_year": 2026}, "role": "finance", "data_as_of": "2026-06-27 02:00:00"}
finance, misspelt dimension, is_error: True
finance, misspelt dimension, text: Error executing tool query_metric: error: request rejected: refund_rate can't use dimension 'order_region'; did you mean order__region?
support, net revenue, is_error: False
support, net revenue, answered: no
support, net revenue, text block is the same JSON: yes
support, net revenue, reason: forbidden: the support role may not see net_revenue
output schema requires: text, answer

A host's code can check each answer field by field. Finance's refund rates came back as structured rows, AMER 7.11%, APAC 6.02%, EMEA 8.45%, computed on finance's own database, whose copy of the calendar gives each day its fiscal year. The provenance has these fields: source, metric, sql, filters, role, data_as_of. Without the SQL, the provenance reads {"source": "metric", "metric": "refund_rate", "filters": {"metric_time__fiscal_year": 2026}, "role": "finance", "data_as_of": "2026-06-27 02:00:00"}. The text block carries the same JSON as the structured content, and the output schema requires text, answer.

The misspelt dimension came back with is_error set and the text "Error executing tool query_metric: error: request rejected: refund_rate can't use dimension 'order_region'; did you mean order__region?". The suggestion is chapter 6's, and the model can act on it. The words before it aren't the server's: the SDK's tool wrapper puts "Error executing tool" and the tool's name in front of the message of any ToolError a tool raises (mcp/server/mcpserver/tools/base.py). The in-process agent never showed the model that prefix, and Answer questions through a host measures what it changes.

Support's net revenue came back without is_error, as an answer that declines, with the reason "forbidden: the support role may not see net_revenue". We return a refusal as an answer, not an error, on purpose. An error invites the model to correct its request and try again, and there's no request support can correct into net revenue. A decline ends the run, as it did in chapter 9, and the host's code can see from the structured reason that the access rules, not the model, made the decision.

Working rule: Return a pydantic model from every tool, so that each answer travels as structured content with its rows, its role, its filters and its data's freshness, and a host's code can check them. Raise a tool error for a request the model can fix, with a message that says how. Return a refusal for access as an answer that declines, with its reason, so the host ends the run instead of letting the model try another way in.

Prueba el servidor en memoria

Último cambio en la edición 2026.11.12

Las respuestas estructuradas del servidor semántico lo hacen comprobable por sus campos, y las pruebas que importan son las que tratan del acceso: un servidor construido para un rol nunca debe responder como si fuera otro. Pruebas así deben ejecutarse en cada cambio, por lo que no pueden necesitar un puerto ni un proceso. El Client del SDK de Python se conecta a un objeto de servidor en el mismo proceso cuando le pasas uno en lugar de una URL, y raise_exceptions=True hace que un fallo fuera del cuerpo de una herramienta llegue con su mensaje real, como explica Model Context Protocol in Practice en prueba las herramientas en memoria. La misma sección enumera lo que tales pruebas no alcanzan, como las cabeceras y las comprobaciones de origen.

Cada prueba del servidor construye un servidor para un rol, llama a una herramienta mediante un cliente en memoria y verifica el contenido estructurado. Las pruebas cubren las reglas que el capítulo 9 midió, y la base de datos que hay debajo: el responsable de EMEA obtiene el resultado de referencia para gq-017; el responsable de EMEA que pide APAC es rechazado como prohibido; la base de datos propia del servidor del responsable, consultada directamente sin ninguna política de por medio, no contiene pedidos de otra región; el catálogo de soporte oculta cada métrica que lee los ingresos, y solo esas; los grupos pequeños de marketing se suprimen; y una dimensión mal escrita es un error de herramienta que sugiere la correcta. El libro no fija un ejecutor de pruebas, así que el archivo usa un pequeño auxiliar en lib/semantic_server.py; bajo pytest, cada una sería una prueba asíncrona normal.

semantic-server-tests.py Python 3.12.15 · anyio 4.16.0 · duckdb 2.0.0 · mcp 2.3.0 · pydantic 2.14.3 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""In-memory tests of the semantic server, one role per server, and one check that a test can fail. The prose'spoint rests on the final line: the lead's request on an analyst's server must differ from the lead's gold."""import anyiofrom lib.golden import golden_result, load_golden, results_matchfrom lib.semantic import loadfrom lib.semantic_server import build_server, call, run_testsfrom lib.warehouse import connectcon, layer = connect(), load()server = lambda role, region=None: build_server(role, region, con, layer)      # each on the role's own databasegold = golden_result(con, next(q for q in load_golden() if q.question_id == "gq-017"))lead_request = {"metrics": ["net_revenue"], "group_by": ["order__country"], "filters": {"metric_time__year": 2025}}HIDDEN_FROM_SUPPORT = {"average_order_value", "gross_revenue", "line_net_revenue", "net_revenue", "refund_rate"}async def test_lead_answer_matches_the_golden_result():    result = await call(server("regional_lead", "EMEA"), "query_metric", lead_request)    assert results_match(result.structured_content["answer"]["rows"], gold)async def test_lead_cannot_ask_for_another_region():    result = await call(server("regional_lead", "EMEA"), "query_metric", {"metrics": ["orders"],                        "filters": {"order__region": "APAC"}})    assert not result.is_error and result.structured_content["answer"]["reason"].startswith("forbidden")async def test_lead_database_holds_no_other_region():        # the policy layer bypassed: SQL straight to the database    regions = server("regional_lead", "EMEA").database.execute("SELECT DISTINCT region FROM analytics.fct_orders")    assert regions.fetchall() == [("EMEA",)]async def test_support_catalog_hides_every_revenue_metric():    listed = (await call(server("support"), "list_metrics", {})).structured_content["text"]    assert HIDDEN_FROM_SUPPORT == set(layer.metrics) - {line[2:].split(":")[0] for line in listed.splitlines()}async def test_marketing_small_groups_are_suppressed():    result = await call(server("marketing"), "query_metric", {"metrics": ["orders"], "group_by":                        ["order__channel", "order__country"], "filters": {"metric_time__month": "2026-06"}})    assert any("(under 10)" in row for row in result.structured_content["answer"]["rows"])async def test_unknown_dimension_is_a_tool_error_with_a_hint():    result = await call(server("finance"), "query_metric", {"metrics": ["orders"], "group_by": ["order_region"]})    assert result.is_error and "did you mean order__region?" in result.content[0].textasync def main():    passed = await run_tests(globals())    print(f"tests passed: {passed} of {passed}")    unbound = (await call(server("analyst"), "query_metric", lead_request)).structured_content["answer"]["rows"]    differs = not results_match(unbound, gold)   # the analyst's server returns every country, so the lead's gold must not match    assert differs    print(f"the lead's request on an analyst's server differs from the lead's gold: {'yes' if differs else 'no'}")anyio.run(main)
Salidapython semantic-server-tests.py
test_lead_answer_matches_the_golden_result: passed
test_lead_cannot_ask_for_another_region: passed
test_lead_database_holds_no_other_region: passed
test_support_catalog_hides_every_revenue_metric: passed
test_marketing_small_groups_are_suppressed: passed
test_unknown_dimension_is_a_tool_error_with_a_hint: passed
tests passed: 6 of 6
the lead's request on an analyst's server differs from the lead's gold: yes

La ejecución informa 6 of 6. Una prueba que pasa solo vale algo si puede fallar, así que la ejecución también envía la solicitud de la primera prueba al servidor de un analista y compara el resultado con el resultado de referencia del responsable. Difiere del resultado de referencia del responsable, como debe ser, porque el servidor del analista devuelve todos los países. Así, la primera prueba detectaría un servidor que perdió su vinculación.

Estas pruebas comprueban el servidor, no el transporte. Pasan por la validación de argumentos, la salida estructurada y el manejo de errores del SDK, que es de donde viene el prefijo de error, pero ninguna solicitud lleva un token. Para un despliegue HTTP, añade al menos una prueba sobre HTTP que envíe tokens de dos roles y compruebe que cada uno recibe sus propias filas, y otra con un token emitido para otro servidor, que debe ser rechazado.

Regla práctica: Prueba las reglas de cada rol mediante un cliente en memoria, con un servidor por rol y verificaciones sobre la respuesta estructurada, e incluye una comprobación que falle cuando la vinculación sea incorrecta. Usa los resultados de las preguntas de oro como valores esperados, de modo que las pruebas y las puntuaciones coincidan en lo que significa correcto. Añade pruebas sobre HTTP para lo que un cliente en memoria no puede enviar, empezando por los tokens.

Esta parte aún no está traducida, así que está en inglés.

Answer questions through a host

Último cambio en la edición 2026.11.15

The tests show that the semantic server answers each tool call as the in-process agent would. The last question is whether an agent answers as well through it. A host is the application that runs the model and calls the server's tools for it, and the host here is the book's own: chapter 1's agent loop, run_agent() in lib/agent.py, with chapter 6's prompt and the recorded model, Qwen3-4B-Instruct-2507, that every chapter replays.

The only new piece is ServerToolbox in lib/semantic_server.py. ServerToolbox has the call() method the loop expects, and makes each call through an MCP client. ask_through_server() opens a client on a server and runs the loop in a worker thread, so that each tool call can reach the server on the event loop. For gq-017, the host made the calls list_metrics, query_metric: the first fills the prompt's catalog, and the second carries the model's request. A model's call that isn't a JSON object, or names a tool the server doesn't list, gets the in-process agent's message from the host without reaching the server, with the tools named in the in-process order. Model Context Protocol in Practice builds a general host in run the host loop; this one stays as thin as the book's loop.

Replay needs the model to see exactly what it saw when it was recorded, and over MCP it mostly does: the catalog and the prompt are the same, and so is every successful tool result's text. A tool error is the exception. Its text carries the SDK's prefix, so the model's next call has a prompt that no earlier recording holds. The recording mcp-host-runs, made with recordings/record_mcp_host.py, holds the replies to those calls only, from the same pinned model and settings. Every golden question runs twice, in process as chapter 9 measured it and through a server built for the question's role, and the example compares the two outcomes question by question.

host-asks-the-server.py Python 3.12.15 · anyio 4.16.0 · duckdb 2.0.0 · mcp 2.3.0 · pydantic 2.14.3 · pyyaml 6.0.3 · sqlglot 30.31.0 Superado
"""The book's agent as an MCP host on every golden question, each tool on the asker's server, against chapter 9.The `same outcome as in process` line settles how many outcomes held, and the two questions that changed,`gq-013` and `gq-014`, each met a tool error."""from collections import Counterimport anyiofrom lib.agent import run_agentfrom lib.golden import golden_result, grade, load_goldenfrom lib.metric_tools import catalogfrom lib.model import RecordedModelsfrom lib.policies import PolicyLayer, PolicyToolbox, policy_forfrom lib.prompts import metrics_first_promptfrom lib.semantic import loadfrom lib.semantic_server import ask_through_server, build_serverfrom lib.warehouse import connectcon, layer = connect(), load()model = RecordedModels("metric-agent-runs", "policy-agent-runs", "mcp-host-runs")   # ch 11 recorded the restasync def main():    counts, changed, details, errors = Counter(), [], [], 0    for q in load_golden():        seen_as = PolicyLayer(layer, policy_for(q.role, q.region or None), con)        local = run_agent(q.question, metrics_first_prompt(catalog(seen_as)), model, PolicyToolbox(con, seen_as), 4)        trace, calls = await ask_through_server(build_server(q.role, q.region or None, con, layer), q.question, model)        outcomes = [grade(q, t.answer, golden_result(con, q)) for t in (local, trace)]        counts[q.split, q.kind, "questions"] += 1        counts[q.split, q.kind, "correct"] += outcomes[1] == "correct"        errors += any("is_error" in c for c in calls)        if outcomes[0] != outcomes[1]:            changed.append(f"{q.question_id} ({q.split}, {q.kind}): {outcomes[0]} in process, "                           f"{outcomes[1]} over MCP, by {trace.steps[-2].tool}")   # the last tool call ended the run            details += [f"{q.question_id} first request's filters: {trace.steps[0].arguments['filters']}",   # the model's first call                        f"{q.question_id} asked: {trace.answer.reason.splitlines()[0]}"]        if q.question_id == "gq-017":            print(f"gq-017 calls: {', '.join(calls)}")    for split in ("dev", "test"):        for kind in ("answer", "decline", "forbidden"):            print(f"{split} {kind} correct over MCP: {counts[split, kind, 'correct']} of "                  f"{counts[split, kind, 'questions']}")    print(f"runs with a tool error: {errors}")    total = len(load_golden())    print(f"same outcome as in process: {total - len(changed)} of {total}")    print("\n".join(changed + details) or "no outcome changed")   # one line per changed question, then detailsanyio.run(main)
Salidapython host-asks-the-server.py
gq-017 calls: list_metrics, query_metric
dev answer correct over MCP: 11 of 17
dev decline correct over MCP: 3 of 4
dev forbidden correct over MCP: 3 of 3
test answer correct over MCP: 6 of 17
test decline correct over MCP: 4 of 4
test forbidden correct over MCP: 3 of 3
runs with a tool error: 11
same outcome as in process: 46 of 48
gq-013 (dev, answer): correct in process, declined over MCP, by ask_back
gq-014 (dev, answer): correct in process, declined over MCP, by ask_back
gq-013 first request's filters: {'order__order_date': '2026-05'}
gq-013 asked: Are you looking for orders in the entire month of May 2026, or specifically on a single day in May 2026?
gq-014 first request's filters: {'order__order_date': '2026-05'}
gq-014 asked: Do you mean orders placed in the entire month of May 2026 or on a specific day in May 2026?

Through the server, the agent kept its in-process outcome on 46 of 48 questions. On the dev split's answer questions, the golden questions used while building, it scored 11 of 17, against 13 of 17 in process.

On the test split the score matched the in-process one: 6 of 17, against 6 of 17.

Every forbidden question was declined, 3 of 3 on dev and 3 of 3 on test, because the policy hides what the role may not see and refuses what it may not ask, as in chapter 9.

Only gq-013 and gq-014 changed, and both went through a tool error. 11 runs met one, and the rest kept their outcome. Both ask about orders in May 2026, and the model's first request had the filters {'order__order_date': '2026-05'}, which validation rejects with a hint to filter metric_time__month instead. In process, the model followed the hint and got the right count. Over MCP, it read the same hint after "Error executing tool query_metric:", and asked the person back instead: "Are you looking for orders in the entire month of May 2026, or specifically on a single day in May 2026?"

The printed line for gq-013 reads correct in process, declined over MCP, by ask_back, and gq-014's is the same. That's one sample per run at temperature 0.7, so it doesn't show that the prefix caused the change, only that a different text gave a different draw. It does show that an outcome can move with nothing changed but the transport's wording, and that only a score on the golden questions finds it.

Treat what the server returns as data in the host as well. OWASP's Top 10 for LLM applications lists an MCP server's output among the carriers of indirect prompt injection (OWASP, LLM01:2026), and a metric answer carries values from the warehouse, such as product names, that chapter 9 showed can hold instructions. The host shows the person the structured answer with its provenance, and never a model's retelling of it unchecked. Model Context Protocol in Practice covers the host's side in treat ticket text as untrusted data.

Working rule: Put the server under the host you already measured, and score it on the golden questions before anyone uses it, because the transport can change what the model reads. Compare outcomes question by question with the in-process runs, and read every run that changed. Record what the new text produces rather than editing the server's messages to match old recordings, and show people the structured answer with its provenance.

Qué sale mal en producción

Último cambio en la edición 2026.11.12

Cuando se sirve sobre MCP, los riesgos de la capa semántica se concentran en sus bordes: quién está conectado, qué más conecta el host y qué SDK responde por el servidor.

Un solo proceso atiende a varias personas. Un servidor stdio vinculado a un rol solo es seguro mientras el host de una persona lo posea. Si lo envuelves en un proceso compartido, o lo pones detrás de HTTP sin tokens, cada cual obtiene el rol de quien lo arrancó. El servidor semántico tal como está construido aquí no escribe ningún registro de auditoría, así que un despliegue debería registrar la entrada del capítulo 9 por cada respuesta, con el principal para el que se construyó el servidor. Allí lo notarías: un principal cuyas peticiones llegan desde varios usuarios o hosts, o a un ritmo que ninguna persona sostendría. Atiende a más de una persona solo por HTTP, con el rol de cada petición tomado de su token.

El rol del token y el archivo de políticas no coinciden. Una afirmación que nombre un rol que roles.toml no tiene, o un responsable regional sin región, debe fallar en modo seguro. policy_for() lanza PolicyError en ambos casos, y un servidor que lo capture y caiga a un rol por defecto ha deshecho el vínculo. Prueba la asignación de afirmaciones a roles con tokens para cada rol y para ninguno.

La conexión del servidor pesa más que su rol. La política restringe las consultas, pero es la base de datos la que decide a qué puede llegar una consulta. Un servidor que vincula el rol del responsable y luego consulta con la conexión del analista está a un error de una fuga. Abre la base de datos de solo lectura propia del rol al vincularlo, como hace build_server(), y comprueba en una prueba que la conexión no puede leer las filas de otra región, como hacen las pruebas.

Un host guarda en caché un catálogo antiguo. En la revisión 2026-07-28, los resultados de listado pueden llevar una vigencia y un ámbito de caché, así que los hosts pueden reutilizarlos (Cache list results). list_metrics es una llamada a herramienta, así que el protocolo no cachea su catálogo, pero un host que lo cachee de todos modos mostrará una métrica después de que la política la haya quitado. Las reglas de acceso siguen rechazando la petición, así que el coste es un rechazo por «forbidden» en un caso donde el modelo habría declinado por sí mismo.

Una actualización del SDK cambia lo que lee el modelo. El prefijo de los errores de herramienta procede del SDK, no del código del servidor, y lo mismo ocurre con el texto de los errores de validación de argumentos. Una versión nueva puede reformular cualquiera de los dos, y el comportamiento del agente tras un error cambia con ellos. Fija la versión del SDK, vuelve a ejecutar las preguntas de referencia a través del host en cada actualización y revisa las ejecuciones cuyo resultado cambió.

Dos servidores describen las mismas métricas. Los proveedores también sirven capas semánticas sobre MCP. El servidor MCP de dbt ofrece herramientas de Semantic Layer llamadas list_metrics, get_dimensions y query_metrics, entre otras, para proyectos en la plataforma de dbt (dbt Labs), y el servidor MCP gestionado de Snowflake responde preguntas sobre vistas semánticas mediante Cortex Analyst, usando el rol por defecto del usuario que se conecta y un permiso aparte para cada herramienta (Snowflake). Son descripciones que dan los proveedores de sus propios productos. Si un host conecta el servidor de un proveedor y el tuyo, su modelo ve dos herramientas list_metrics con dos juegos de definiciones. Da a cada host un servidor por capa semántica, y si necesita dos, pon nombres distintos a las herramientas, como hace Model Context Protocol in Practice en nombrar herramientas entre servidores.

Un cliente de una revisión anterior se conecta. mcp 2.3.0 también atiende a clientes de las revisiones de 2025 mediante el antiguo handshake, y el servidor de dbt fija la línea 1.x del SDK (dbt-mcp). Las herramientas del servidor semántico no dependen de la revisión, pero las sesiones y la cancelación de un despliegue HTTP sí; Model Context Protocol in Practice lo trata en atender a clientes antiguos y nuevos durante la ventana.

Regla práctica: Ejecuta un servidor stdio por persona, o HTTP con el rol de cada petición tomado de su token, y falla en modo seguro ante cualquier afirmación que el archivo de políticas no conozca. Consulta con la base de datos de solo lectura propia del rol, no con una compartida. Fija el SDK y vuelve a ejecutar las preguntas de referencia a través del host cada vez que cambie. Mantén un servidor por capa semántica en cada host, registra una entrada de auditoría por cada respuesta y revisa las que correspondan a un principal que parezca compartido por más de una persona.

Decisiones que tomó este capítulo

Aquí termina el libro. Tú partiste de un agente que escribía SQL sobre un esquema y fallaba en la mayoría de las preguntas doradas. Ahora puedes construir la versión que la tienda puede usar: una que primero consulta métricas gobernadas, escribe SQL solo en la base de datos de solo lectura de su rol, dentro de guardas, se abstiene cuando no puede responder, mantiene a cada rol dentro de lo que puede ver, y sirve todo eso a cualquier host mediante MCP. Sobre todo, puedes medir cada cambio con preguntas doradas escritas a partir de tu propio trabajo, de modo que el próximo cambio que hagas sea uno que puedas demostrar.

  • El servidor semántico ofrece las cinco herramientas del capítulo 6, cada una como una llamada fina a PolicyToolbox del capítulo 9, de modo que el servidor y el agente en proceso ejecutan el mismo código.
  • Una sola lista de herramientas para todos los roles, en orden de nombre y marcada como de solo lectura; el rol cambia lo que devuelven list_metrics y las demás herramientas.
  • El rol se vincula al construir el servidor: desde el entorno para stdio, y desde un token verificado en cada solicitud para HTTP. Ninguna herramienta acepta un argumento role.
  • Cada servidor consulta la base de datos de solo lectura de su propio rol, la base de datos del capítulo 7 con las vistas y el calendario de la capa semántica añadidos; la política es la segunda capa.
  • Cada herramienta devuelve contenido estructurado: el texto que se muestra al modelo, y la respuesta con sus filas y procedencia.
  • Una solicitud que el modelo puede corregir es un error de herramienta; una solicitud que el rol no puede hacer es una respuesta que se niega, con un motivo que empieza por "forbidden".
  • El servidor se prueba en memoria, un rol por servidor, contra los resultados dorados, con una verificación que falla cuando la vinculación es incorrecta.
  • La vía HTTP se describe, no se ejecuta: los ejemplos no abren ningún socket, y un cliente en memoria no lleva token, así que la correspondencia de un token verificado a un rol necesita sus propias pruebas sobre HTTP.
  • El host es el bucle y el prompt propios del libro. Las llamadas que contienen las grabaciones anteriores se reproducen; mcp-host-runs contiene solo las llamadas que siguen a un texto de error que el SDK cambió.

Este capítulo, en esta edición

Edición 2026.11.15Ejemplos verificados el 19 de nov de 2026Superan la prueba 5 de 5 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.15.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 11 de 11: Serve the semantic layer over MCP

  1. Convierte métricas en herramientas
  2. Carry the caller's role into every query
  3. Return answers with their provenance
  4. Prueba el servidor en memoria
  5. Answer questions through a host
  6. Qué sale mal en producción
  7. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos