Serve the semantic layer over MCP
阅读约需 85分钟 分钟,7节中含5个示例。
这部分尚未翻译,因此以英文显示。
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.
这部分尚未翻译,因此以英文显示。
Turn metrics into tools
An MCP tool is a name, a description the model reads, a JSON Schema for its arguments and, optionally, a schema for its result. A client discovers a server's tools with tools/list and calls one with tools/call. The specification says the list must not vary per connection, though it may vary with the authorization presented on the request, and that servers should return tools in a deterministic order (tools). So the questions for a semantic layer are which tools to offer, and whether a role should see fewer of them.
We recommend offering the tools the agent already has. Chapter 6 chose five for the shop's agent: list_metrics, describe_metric, query_metric, ask_back and cannot_answer. They were measured on the golden questions, whose answers were checked by running them, and they ask the model to choose a metric request, never to write SQL. build_server() in lib/semantic_server.py registers one MCP tool for each, with a description the model reads and typed arguments, and each tool body calls the same method of chapter 9's PolicyToolbox that the in-process agent calls. The tools are registered in name order. Each is marked read-only, idempotent and closed-world with MCP's tool annotations. Model Context Protocol in Practice explains how to write descriptions the model reads and why annotations are hints, not guarantees.
What a role changes is easiest to see side by side: a server for the analyst, who sees everything, and one for the support team, who may see no revenue. The code lists each server's tools and compares its list_metrics catalog with the one the in-process agent puts in its prompt.
1"""The semantic layer as an MCP server: the tools it lists, what query_metric takes, and each role's catalog.2The `support, metrics` line settles that support's catalog holds no revenue metric, and the `same catalog as the3in-process agent` lines settle that each catalog is the prompt's own text."""4import anyio5from mcp import Client67from lib.metric_tools import catalog8from lib.policies import PolicyLayer, policy_for9from lib.semantic import load10from lib.semantic_server import build_server11from lib.warehouse import connect1213con, layer = connect(), load()141516async def main():17 listed = {}18 for role in ("analyst", "support"):19 async with Client(build_server(role, shop=con, layer=layer)) as client: # in memory: no port, no process20 tools = (await client.list_tools()).tools21 text = (await client.call_tool("list_metrics", {})).structured_content["text"]22 listed[role] = [t.name for t in tools]23 metrics = [line[2:].split(":")[0] for line in text.splitlines()] # catalog lines start with "- ", then the name24 print(f"{role}, tools: {', '.join(listed[role])}")25 print(f"{role}, metrics in list_metrics: {len(metrics)}")26 print(f"{role}, metrics: {', '.join(metrics)}")27 in_process = catalog(PolicyLayer(layer, policy_for(role), con))28 same = text == in_process # PolicyLayer builds the in-process prompt's catalog, so MCP must match it29 assert same30 print(f"{role}, same catalog as the in-process agent: {'yes' if same else 'no'}")31 query = next(t for t in tools if t.name == "query_metric")32 print(f"query_metric inputs: {', '.join(query.input_schema['properties'])}")33 print(f"query_metric requires: {', '.join(query.input_schema['required'])}")34 print(f"tools marked read-only: {sum(t.annotations.read_only_hint for t in tools)} of {len(tools)}")35 print(f"tools with a role input: {sum('role' in t.input_schema['properties'] for t in tools)}")36 print(f"same tool list for both roles: {listed['analyst'] == listed['support']}")373839anyio.run(main)
python list-metric-tools.pyanalyst, 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
Both servers list the same tools: ask_back, cannot_answer, describe_metric, list_metrics, query_metric. What differs is the catalog. The analyst's list_metrics returns 10 metrics and support's 5: orders, units_sold, refunds, order_refunds, new_customers. Every revenue metric is gone from support's catalog, because chapter 9's PolicyLayer hides any metric that reads a column its role is denied. For both roles, the catalog over MCP is the same text the in-process agent puts in its prompt. That matters for the host: an unchanged catalog means an unchanged prompt.
query_metric takes metrics, group_by, filters, order_by, limit and requires only metrics. Of the server's tools, 5 of 5 are marked read-only, and 0 take an argument called role, which is the subject of the next section.
Keeping one tool list for every role was a choice. The specification would allow support's server to list fewer tools, but each of the five tools is useful to every role, and the role changes what a tool returns, not whether it exists. A role that can't use a tool at all is the case for shortening the list, and Model Context Protocol in Practice covers scope tools by what the token allows. The cost of a long list is the subject of the same book's keep the tool list small.
Working rule: Serve the tools your agent was measured with, each one a thin call into the same code the in-process agent uses, so that the server can't drift from what you tested. List them in a fixed order and mark them read-only. Let the role change what a tool returns, and shorten the tool list only when a role can't use a tool at all.
这部分尚未翻译,因此以英文显示。
Carry the caller's role into every query
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.
1"""gq-017 from EMEA's regional lead, sent with role "analyst": a server that takes the role as an argument obeys it,2and one that binds the role when it is built ignores it, and queries a database that holds only the lead's rows.3The `role as argument, countries` line shows every country a request-supplied role returns, and the `role bound at4build, countries` line settles that a server built for the lead returns EMEA's countries only."""5import anyio6from mcp import Client7from mcp.server.mcpserver import MCPServer89from lib.policies import PolicyLayer, PolicyToolbox, policy_for10from lib.semantic import MetricRequest, load11from lib.semantic_server import build_server, server_from_environment12from lib.warehouse import connect1314con, layer = connect(), load()15naive = MCPServer("role-as-argument")161718@naive.tool()19def query_metric(metrics: list[str], group_by: list[str] = [], filters: dict = {}, role: str = "analyst",20 region: str | None = None) -> list[list]:21 """The anti-pattern: whoever calls the tool says who they are, and it queries the whole warehouse."""22 toolbox = PolicyToolbox(con, PolicyLayer(layer, policy_for(role, region), con))23 return [list(row) for row in toolbox.query_metric({"metrics": metrics, "group_by": group_by,24 "filters": filters}).answer.rows]252627request = {"metrics": ["net_revenue"], "group_by": ["order__country"], "filters": {"metric_time__year": 2025},28 "role": "analyst"} # the lead's request, with a role the lead doesn't have29environment = {"SHOP_ROLE": "regional_lead", "SHOP_REGION": "EMEA"} # what a host sets for a stdio server303132async def main():33 servers = {"role as argument": naive, "role bound at build": build_server("regional_lead", "EMEA", con, layer),34 "role from the environment": (stdio := server_from_environment(environment, con))}35 for name, server in servers.items():36 async with Client(server) as client:37 result = (await client.call_tool("query_metric", request)).structured_content38 rows = result["result"] if "result" in result else result["answer"]["rows"]39 print(f"{name}, countries: {', '.join(row[0] for row in rows)}")40 if "answer" in result:41 provenance = result["answer"]["provenance"]42 print(f"{name}, provenance: role {provenance['role']}, row filter {provenance['filters']['row filter']}")43 # The policy bypassed: the plain semantic layer, which applies no role, on the stdio server's own database.44 bypass = layer.query(stdio.database, MetricRequest.from_arguments({k: v for k, v in request.items() if k != "role"}))45 print(f"role from the environment, no policy, countries: {', '.join(row[0] for row in bypass.rows)}")464748anyio.run(main)
python role-bound-at-build.pyrole 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).
这部分尚未翻译,因此以英文显示。
Return answers with their provenance
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.
1"""What a host receives from query_metric: an answer with its provenance as structured content, a request the model2can 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 that3the finance answer's text matches its structured content, and `support, net revenue` with `is_error: False` and4`answered: no` settles that a forbidden request declines rather than errors."""5import json67import anyio8from mcp import Client910from lib.semantic import load11from lib.semantic_server import build_server12from lib.warehouse import connect1314con, layer = connect(), load()15asks = {"finance, refund rate": ("finance", {"metrics": ["refund_rate"], "group_by": ["order__region"],16 "filters": {"metric_time__fiscal_year": 2026}}),17 "finance, misspelt dimension": ("finance", {"metrics": ["refund_rate"], "group_by": ["order_region"]}),18 "support, net revenue": ("support", {"metrics": ["net_revenue"], "filters": {"metric_time__year": 2025}})}192021async def main():22 for name, (role, request) in asks.items():23 async with Client(build_server(role, shop=con, layer=layer)) as client:24 tool = next(t for t in (await client.list_tools()).tools if t.name == "query_metric")25 result = await client.call_tool("query_metric", request)26 print(f"{name}, is_error: {result.is_error}")27 if result.is_error:28 print(f"{name}, text: {result.content[0].text}")29 continue30 answer = result.structured_content["answer"]31 answered = answer["answered"]32 assert answered == (role != "support") # support may see no revenue, so its answer declines33 print(f"{name}, answered: {'yes' if answered else 'no'}")34 same = json.loads(result.content[0].text) == result.structured_content # the specification asks for this JSON in the text block35 assert same36 print(f"{name}, text block is the same JSON: {'yes' if same else 'no'}")37 if answer["answered"]:38 print(f"{name}, rows: {', '.join(f'{region} {rate:.2%}' for region, rate in answer['rows'])}")39 print(f"{name}, provenance fields: {', '.join(answer['provenance'])}")40 print(f"{name}, provenance: {json.dumps({k: v for k, v in answer['provenance'].items() if k != 'sql'})}")41 else:42 print(f"{name}, reason: {answer['reason']}")43 print(f"output schema requires: {', '.join(tool.output_schema['required'])}")444546anyio.run(main)
python tool-result-with-provenance.pyfinance, 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.
在内存中测试服务器
语义服务器的结构化回答使它可以按字段进行测试,而真正重要的测试与访问权限有关:为某一角色构建的服务器,绝不能以另一角色的身份作答。这类测试应在每次变更时运行,因此不能依赖端口或进程。向 Python SDK 的 Client 传入服务器对象而不是 URL 时,它会连接到同一进程中的该服务器;而 raise_exceptions=True 会让工具主体之外的失败带着真实的错误信息返回,这一点在《Model Context Protocol in Practice》的在内存中测试工具中有说明。该节还列出了这类测试无法覆盖的内容,例如请求头和来源检查。
服务器的每个测试都为一个角色构建一台服务器,通过内存中的客户端调用一个工具,并对结构化内容进行断言。这些测试涵盖第 9 章所度量的规则,以及这些规则之下的数据库:EMEA 负责人对 gq-017 得到黄金结果;EMEA 负责人请求 APAC 的数据时,会被作为禁止访问而拒绝;该负责人所用服务器自己的数据库在不经任何策略过滤、直接查询时,不包含其他区域的订单;客服的目录隐藏所有读取收入的指标,且只隐藏这些指标;市场部的小分组被抑制;拼错的维度是一个工具错误,并会提示正确的维度。本书没有指定测试运行器,因此该文件在 lib/semantic_server.py 中使用了一个小型辅助函数;若使用 pytest,每个测试都会是普通的异步测试。
1"""In-memory tests of the semantic server, one role per server, and one check that a test can fail. The prose's2point rests on the final line: the lead's request on an analyst's server must differ from the lead's gold."""3import anyio45from lib.golden import golden_result, load_golden, results_match6from lib.semantic import load7from lib.semantic_server import build_server, call, run_tests8from lib.warehouse import connect910con, layer = connect(), load()11server = lambda role, region=None: build_server(role, region, con, layer) # each on the role's own database12gold = golden_result(con, next(q for q in load_golden() if q.question_id == "gq-017"))13lead_request = {"metrics": ["net_revenue"], "group_by": ["order__country"], "filters": {"metric_time__year": 2025}}14HIDDEN_FROM_SUPPORT = {"average_order_value", "gross_revenue", "line_net_revenue", "net_revenue", "refund_rate"}151617async def test_lead_answer_matches_the_golden_result():18 result = await call(server("regional_lead", "EMEA"), "query_metric", lead_request)19 assert results_match(result.structured_content["answer"]["rows"], gold)202122async def test_lead_cannot_ask_for_another_region():23 result = await call(server("regional_lead", "EMEA"), "query_metric", {"metrics": ["orders"],24 "filters": {"order__region": "APAC"}})25 assert not result.is_error and result.structured_content["answer"]["reason"].startswith("forbidden")262728async def test_lead_database_holds_no_other_region(): # the policy layer bypassed: SQL straight to the database29 regions = server("regional_lead", "EMEA").database.execute("SELECT DISTINCT region FROM analytics.fct_orders")30 assert regions.fetchall() == [("EMEA",)]313233async def test_support_catalog_hides_every_revenue_metric():34 listed = (await call(server("support"), "list_metrics", {})).structured_content["text"]35 assert HIDDEN_FROM_SUPPORT == set(layer.metrics) - {line[2:].split(":")[0] for line in listed.splitlines()}363738async def test_marketing_small_groups_are_suppressed():39 result = await call(server("marketing"), "query_metric", {"metrics": ["orders"], "group_by":40 ["order__channel", "order__country"], "filters": {"metric_time__month": "2026-06"}})41 assert any("(under 10)" in row for row in result.structured_content["answer"]["rows"])424344async def test_unknown_dimension_is_a_tool_error_with_a_hint():45 result = await call(server("finance"), "query_metric", {"metrics": ["orders"], "group_by": ["order_region"]})46 assert result.is_error and "did you mean order__region?" in result.content[0].text474849async def main():50 passed = await run_tests(globals())51 print(f"tests passed: {passed} of {passed}")52 unbound = (await call(server("analyst"), "query_metric", lead_request)).structured_content["answer"]["rows"]53 differs = not results_match(unbound, gold) # the analyst's server returns every country, so the lead's gold must not match54 assert differs55 print(f"the lead's request on an analyst's server differs from the lead's gold: {'yes' if differs else 'no'}")565758anyio.run(main)
python semantic-server-tests.pytest_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
运行报告 6 of 6。只有可能失败的测试,其通过才有价值,所以这次运行还会把第一个测试的请求发送到分析师的服务器,并将结果与负责人的黄金结果比较。二者不同,这正是应有的结果,因为分析师的服务器会返回所有国家的数据。由此可见,第一个测试能够发现丢失了绑定的服务器。
这些测试检查的是服务器,而不是传输层。它们经过 SDK 的参数校验、结构化输出和错误处理,错误前缀正是由此而来,但没有任何请求携带令牌。对于 HTTP 部署,至少应再增加一个基于 HTTP 的测试,为两个角色发送令牌,并检查各自得到的是自己的行;另加一个测试,使用为另一台服务器签发的令牌,该请求必须被拒绝。
工作准则: 通过内存中的客户端测试每个角色的规则,每个角色一台服务器,并对结构化回答进行断言,同时包含一项在绑定错误时会失败的检查。以黄金问题的结果作为期望值,使测试与评分对“正确”的含义保持一致。对于内存中的客户端无法发送的内容,增加基于 HTTP 的测试,首先是令牌。
这部分尚未翻译,因此以英文显示。
Answer questions through a host
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.
1"""The book's agent as an MCP host on every golden question, each tool on the asker's server, against chapter 9.2The `same outcome as in process` line settles how many outcomes held, and the two questions that changed,3`gq-013` and `gq-014`, each met a tool error."""4from collections import Counter56import anyio78from lib.agent import run_agent9from lib.golden import golden_result, grade, load_golden10from lib.metric_tools import catalog11from lib.model import RecordedModels12from lib.policies import PolicyLayer, PolicyToolbox, policy_for13from lib.prompts import metrics_first_prompt14from lib.semantic import load15from lib.semantic_server import ask_through_server, build_server16from lib.warehouse import connect1718con, layer = connect(), load()19model = RecordedModels("metric-agent-runs", "policy-agent-runs", "mcp-host-runs") # ch 11 recorded the rest202122async def main():23 counts, changed, details, errors = Counter(), [], [], 024 for q in load_golden():25 seen_as = PolicyLayer(layer, policy_for(q.role, q.region or None), con)26 local = run_agent(q.question, metrics_first_prompt(catalog(seen_as)), model, PolicyToolbox(con, seen_as), 4)27 trace, calls = await ask_through_server(build_server(q.role, q.region or None, con, layer), q.question, model)28 outcomes = [grade(q, t.answer, golden_result(con, q)) for t in (local, trace)]29 counts[q.split, q.kind, "questions"] += 130 counts[q.split, q.kind, "correct"] += outcomes[1] == "correct"31 errors += any("is_error" in c for c in calls)32 if outcomes[0] != outcomes[1]:33 changed.append(f"{q.question_id} ({q.split}, {q.kind}): {outcomes[0]} in process, "34 f"{outcomes[1]} over MCP, by {trace.steps[-2].tool}") # the last tool call ended the run35 details += [f"{q.question_id} first request's filters: {trace.steps[0].arguments['filters']}", # the model's first call36 f"{q.question_id} asked: {trace.answer.reason.splitlines()[0]}"]37 if q.question_id == "gq-017":38 print(f"gq-017 calls: {', '.join(calls)}")39 for split in ("dev", "test"):40 for kind in ("answer", "decline", "forbidden"):41 print(f"{split} {kind} correct over MCP: {counts[split, kind, 'correct']} of "42 f"{counts[split, kind, 'questions']}")43 print(f"runs with a tool error: {errors}")44 total = len(load_golden())45 print(f"same outcome as in process: {total - len(changed)} of {total}")46 print("\n".join(changed + details) or "no outcome changed") # one line per changed question, then details474849anyio.run(main)
python host-asks-the-server.pygq-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.
生产环境中会出什么问题
通过 MCP 提供服务时,语义层的风险集中在它的边缘:谁已连接,宿主还连接了什么,以及由哪个 SDK 来响应服务器。
一个进程为多人服务。 绑定到某一角色的 stdio 服务器,只有在由一个人的宿主独占时才是安全的。如果把它包进共享进程,或者不带令牌地放在 HTTP 之后,每个人得到的都是启动者的角色。这里构建的语义服务器不写审计日志,因此部署时应为每次回答记录第 9 章的条目,并带上服务器构建时所针对的主体。在这里可以发现这样的迹象:同一个主体的请求来自多个用户或多个宿主,或者请求频率高到没有哪个人会这样提问。只有通过 HTTP,并按每个请求的令牌确定角色,才可以为多人服务。
令牌中的角色与策略文件不一致。 如果声明指向 roles.toml 中没有的角色,或者某个区域负责人没有区域,必须以拒绝为默认结果。policy_for() 对这两种情况都会抛出 PolicyError,而如果服务器捕获它并退回到默认角色,就等于撤销了绑定。请用每个角色的令牌以及无角色的令牌,测试从声明到角色的映射。
服务器的连接优先于它的角色。 策略只能收窄查询,但查询能触及什么由数据库决定。如果服务器绑定了负责人的角色,却用分析师的连接去查询,那么只差一个缺陷就会造成泄露。绑定角色时,应像 build_server() 那样打开该角色自己的只读数据库,并像测试那样,在测试中检查该连接无法读取其他区域的行。
宿主缓存了旧目录。 在 2026-07-28 修订版中,列表结果可以带有生存期和缓存范围,因此宿主可以复用它们(缓存列表结果)。list_metrics 是一次工具调用,所以协议不会缓存它的目录;但如果宿主仍然缓存它,就会在策略移除某个指标之后继续显示该指标。访问规则仍会拒绝这个请求,所以代价是得到一次“禁止”拒绝,而本来模型自己就会拒绝。
SDK 升级会改变模型读到的内容。 工具错误的前缀来自 SDK,而不是服务器的代码,参数校验错误的文本也是如此。新版本可能改写其中任何一种,智能体在出错之后的行为也会随之改变。请固定 SDK 版本,每次升级时通过宿主重新运行标准问题集,并查看结果发生变化的那些运行。
两个服务器描述同一批指标。 供应商也通过 MCP 提供语义层。dbt 的 MCP 服务器为 dbt 平台上的项目提供名为 list_metrics、get_dimensions 和 query_metrics 等的 Semantic Layer 工具(dbt Labs),Snowflake 的托管 MCP 服务器则通过 Cortex Analyst 回答基于语义视图的问题,使用连接用户的默认角色,并对每个工具单独授权(Snowflake)。这些是供应商对自家产品的描述。如果宿主同时连接供应商的服务器和你的服务器,它的模型就会看到两个 list_metrics 工具及两套定义。请为每个宿主、每个语义层只配一个服务器;必须配两个时,要让工具名称相互区分,正如 Model Context Protocol in Practice 在跨服务器命名工具中所做的那样。
旧修订版的客户端连接进来。 mcp 2.3.0 还通过旧的握手为使用 2025 修订版的客户端提供服务,而 dbt 的服务器固定使用 SDK 的 1.x 系列(dbt-mcp)。语义服务器的工具不依赖于修订版,但 HTTP 部署的会话和取消机制依赖;Model Context Protocol in Practice 在在过渡期内同时服务新旧客户端中对此有说明。
工作准则: 每人运行一个 stdio 服务器,或者使用 HTTP 并按每个请求的令牌确定角色,对策略文件不认识的任何声明一律拒绝。查询时使用该角色自己的只读数据库,而不是共享的数据库。固定 SDK 版本,并在 SDK 每次变化时通过宿主重新运行标准问题集。每个宿主中每个语义层只保留一个服务器,为每次回答记录审计条目,并查看其中是否有看似被多人共用的主体。
本章所做的决定
全书到此结束。你从一个在数据库模式上编写 SQL、却答错了大多数标准问题的智能体出发。现在,你可以构建商店能够使用的版本:它先查询受治理的指标,只在其角色的只读数据库上、在防护措施之内编写 SQL,无法回答时予以拒答,让每个角色只能看到其被允许查看的内容,并通过 MCP 将这一切提供给任何宿主。最重要的是,你可以用根据自己的工作编写的标准问题来衡量每一次改动,因此你下一次所做的改动是可以证明的。
- **语义服务器提供第 6 章的五个工具,**每个工具都是对第 9 章
PolicyToolbox的一次薄调用,因此服务器与进程内智能体运行的是同一份代码。 - **所有角色共用一份工具列表,**按名称排序并标记为只读;角色改变的是
list_metrics和其他工具所返回的内容。 - **角色在构建服务器时绑定:**stdio 从环境中获取,HTTP 则从每个请求上经过验证的令牌中获取。没有任何工具接受
role参数。 - **每个服务器查询的都是其角色自己的只读数据库,**即第 7 章的数据库,并加入了语义层的视图和日历;策略是第二层防护。
- **每个工具都返回结构化内容:**一部分是展示给模型的文本,另一部分是附带数据行和来源的答案。
- **模型可以自行修正的请求是工具错误;角色无权发出的请求则是拒答的答案,**其理由以 "forbidden" 开头。
- **服务器在内存中测试,每个服务器对应一个角色,**依据标准结果进行测试,并包含一项在绑定错误时会失败的检查。
- **HTTP 路径只做了描述,没有运行:**示例不打开任何套接字,而内存中的客户端不携带令牌,因此从经过验证的令牌到角色的映射需要通过 HTTP 另行测试。
- **宿主就是本书自己的循环和提示词。**此前录制中已有的调用会被重放;
mcp-host-runs只保存在 SDK 更改了错误文本之后发生的那些调用。
本章,在本版次中
版次 2026.11.15示例于 2026年11月19日 通过本章 5个示例 个示例中有 5 个通过
译自英文版图书,版次 2026.11.15。