Serve the semantic layer over MCP

閱讀約需 85 分鐘 分鐘,7 節 中共有 5 個範例。

版次 2026.11.15 範例於 2026年11 月 19 通過測試 78 個範例中有 78 個通過 變更內容

由 AI 翻譯。經人工以英文驗證。 我們如何製作書籍

譯自英文書,版次 2026.11.15。 閱讀原文

此部分尚未翻譯,因此以英文呈現。

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

最近一次變動於第 2026.11.12 版

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.

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 通過
"""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)
輸出python 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

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

最近一次變動於第 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 通過
"""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)
輸出python 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).

此部分尚未翻譯,因此以英文呈現。

Return answers with their provenance

最近一次變動於第 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 通過
"""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)
輸出python 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.

在記憶體中測試伺服器

最近一次變動於第 2026.11.12 版

語意伺服器的結構化回答讓我們能依欄位來測試它,而真正重要的測試都與存取有關:為某一個角色建立的伺服器,絕不能以另一個角色的身分回答。這類測試應該在每次變更時執行,因此不能依賴連接埠或行程。Python SDK 的 Client 在你傳入伺服器物件而非 URL 時,會連線到同一行程內的該伺服器;而 raise_exceptions=True 會讓工具本體之外的失敗帶著真實的訊息回傳,這在 Model Context Protocol in Practice 的在記憶體中測試工具中有說明。同一節也列出了這類測試無法觸及的項目,例如標頭與來源檢查。

伺服器的每個測試都會為一個角色建立伺服器,透過記憶體內的用戶端呼叫一個工具,並對結構化內容進行斷言。這些測試涵蓋第 9 章所衡量的規則,以及規則底下的資料庫:EMEA 主管取得 gq-017 的黃金結果;EMEA 主管要求 APAC 的資料時,會因禁止存取而被拒絕;主管伺服器自己的資料庫在沒有任何政策介入的情況下直接查詢,不含其他地區的訂單;客服的目錄會隱藏每一個讀取營收的指標,且只隱藏這些指標;行銷的小型群組會被抑制;而拼錯的維度會產生一個工具錯誤,並建議正確的維度。本書未指定測試執行器,因此該檔案在 lib/semantic_server.py 中使用一個小型輔助函式;若使用 pytest,每個測試都會是一般的非同步測試。

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 通過
"""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)
輸出python 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

執行結果回報 6 of 6。通過的測試必須有可能失敗才有價值,因此這次執行也會把第一個測試的請求送到分析師的伺服器,並將結果與主管的黃金結果比較。兩者不同,這是應有的結果,因為分析師的伺服器會回傳所有國家。所以第一個測試能夠抓出遺失綁定的伺服器。

這些測試檢查的是伺服器,而不是傳輸層。它們會經過 SDK 的參數驗證、結構化輸出與錯誤處理,錯誤前綴正是來自這裡,但沒有任何請求攜帶權杖。對於 HTTP 部署,至少要加入一個透過 HTTP 的測試,送出兩個角色的權杖,並檢查各自取得自己的資料列;再加入一個使用為另一個伺服器簽發之權杖的測試,該請求必須被拒絕。

實用原則: 透過記憶體內的用戶端測試每個角色的規則,每個角色一個伺服器,並對結構化回答進行斷言,同時納入一項在綁定錯誤時會失敗的檢查。以黃金問題的結果作為預期值,讓測試與分數對「正確」的定義一致。對於記憶體內用戶端無法送出的內容,加上透過 HTTP 的測試,並以權杖為優先。

此部分尚未翻譯,因此以英文呈現。

Answer questions through a host

最近一次變動於第 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 通過
"""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)
輸出python 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.

正式環境中會出什麼問題

最近一次變動於第 2026.11.12 版

透過 MCP 提供服務時,語意層的風險出現在邊界上:誰連上了伺服器、主機還連接了什麼,以及伺服器由哪個 SDK 負責。

一個行程服務多個人。 綁定單一角色的 stdio 伺服器,只有在由一個人的主機獨自擁有時才安全。若把它包進共用行程,或在沒有權杖的情況下放到 HTTP 之後,所有人都會取得啟動者的角色。此處建置的語意伺服器不會寫入稽核日誌,因此部署時應為每個回答記錄第 9 章的項目,並附上伺服器所綁定的主體。你可以從這些現象察覺問題:同一個主體的請求來自多位使用者或多個主機,或請求頻率不是一個人會有的。只有在透過 HTTP、且角色取自每個請求的權杖時,才服務超過一個人。

權杖的角色與政策檔不一致。 若宣告指名了 roles.toml 中沒有的角色,或是沒有區域的區域主管,都必須以拒絕為預設(fail closed)。policy_for() 對這兩種情況都會引發 PolicyError,而若伺服器捕捉它並退回預設角色,就等於推翻了角色綁定。請用每個角色的權杖以及不帶角色的權杖,測試從宣告到角色的對應。

伺服器的連線權限高於其角色。 政策會收斂查詢,但查詢能觸及什麼是由資料庫決定的。若伺服器綁定了主管的角色,卻用分析師的連線進行查詢,距離資料外洩只差一個錯誤。綁定角色時,應如 build_server() 那樣開啟該角色專屬的唯讀資料庫,並像測試那樣,在測試中確認該連線無法讀取其他區域的資料列。

主機快取了舊的目錄。 在 2026-07-28 版本中,列表結果可以帶有存活時間與快取範圍,因此主機可以重複使用它們(快取列表結果)。list_metrics 是工具呼叫,所以協定不會快取它的目錄;但若主機仍然快取,就會在政策移除某個指標之後繼續顯示它。存取規則仍會拒絕該請求,所以代價只是多了一次「禁止」的拒絕回應,而模型原本就會自行拒絕。

SDK 升級改變了模型讀到的內容。 工具錯誤的前綴來自 SDK,而不是伺服器的程式碼,引數驗證錯誤的文字也一樣。新版本可能改寫其中任何一項,代理在錯誤之後的行為也會隨之改變。請固定 SDK 版本,每次升級時都透過主機重跑黃金問題,並檢視結果有變化的那些執行。

兩個伺服器描述相同的指標。 廠商也透過 MCP 提供語意層。dbt 的 MCP 伺服器為 dbt 平台上的專案提供語意層工具,名稱包括 list_metrics、get_dimensions 和 query_metrics 等(dbt Labs);Snowflake 的受管 MCP 伺服器則透過 Cortex Analyst 回答語意檢視上的問題,使用連線使用者的預設角色,並為每個工具另設授權(Snowflake)。這些是廠商對自家產品的描述。如果主機同時連接廠商的伺服器與你的伺服器,其模型會看到兩個 list_metrics 工具,以及兩組定義。請讓每個主機對每個語意層只連一個伺服器;若必須連兩個,就為工具取不同的名稱,如《Model Context Protocol 實務》在跨伺服器為工具命名中所做的。

舊版本的用戶端連線。 mcp 2.3.0 也透過舊的交握方式服務 2025 版本的用戶端,而 dbt 的伺服器固定使用 SDK 的 1.x 系列(dbt-mcp)。語意伺服器的工具不依賴版本,但 HTTP 部署的工作階段與取消機制則會;《Model Context Protocol 實務》在於過渡期間同時服務新舊用戶端中說明了這點。

實用原則: 每個人各用一個 stdio 伺服器,或使用 HTTP 並從每個請求的權杖取得角色,對政策檔不認得的任何宣告一律以拒絕為預設。查詢時使用該角色專屬的唯讀資料庫,而不是共用的資料庫。固定 SDK 版本,並在它每次變動時透過主機重跑黃金問題。每個主機對每個語意層只保留一個伺服器,為每個回答記錄稽核項目,並檢視是否有看似被多人共用的主體。

本章做出的決定

本書到此結束。你從一個在資料庫綱要上撰寫 SQL、卻答錯大多數黃金問題的代理開始。現在,你能建出商店可以實際使用的版本:它先查詢受治理的指標,只在其角色的唯讀資料庫上、於防護機制之內撰寫 SQL,無法回答時選擇拒答,讓每個角色只停留在其可見的範圍內,並透過 MCP 把這一切提供給任何主機。最重要的是,你能用依據自己的工作所寫成的黃金問題來衡量每一項變更,因此你接下來做的每一項變更,都是能夠證明的。

  • **語意伺服器提供第 6 章的五個工具,**每個工具都是對第 9 章的 PolicyToolbox 的一次精簡呼叫,因此伺服器與行程內代理執行的是相同的程式碼。
  • **所有角色共用同一份工具清單,**依名稱排序並標示為唯讀;角色改變的是 list_metrics 與其他工具所回傳的內容。
  • **角色在建置伺服器時綁定:**stdio 由環境變數取得,HTTP 則在每次請求時由已驗證的權杖取得。沒有任何工具接受 role 引數。
  • **每個伺服器都查詢其角色專屬的唯讀資料庫,**也就是第 7 章的資料庫,再加上語意層的檢視表與日曆;政策是第二道防線。
  • **每個工具都回傳結構化內容:**即呈現給模型的文字,以及附有資料列與出處的答案。
  • **模型能自行修正的請求是工具錯誤;角色不得提出的請求則是拒答的答案,**其理由以「forbidden」開頭。
  • **伺服器在記憶體中測試,每個伺服器對應一個角色,**並對照黃金結果,另有一項檢查會在綁定錯誤時失敗。
  • **HTTP 路徑只加以描述,不實際執行:**範例不開啟任何 socket,而記憶體內的用戶端不帶權杖,因此從已驗證權杖到角色的對應,需要另外透過 HTTP 進行測試。
  • **主機就是本書自己的迴圈與提示詞。**先前錄製內容中已有的呼叫會被重播;mcp-host-runs 只保存 SDK 更動錯誤文字之後的那些呼叫。

本章,於本版次中

版次 2026.11.15範例於 2026年11 月 19 通過測試本章 5 個範例 個範例中有 5 個通過

譯自英文書,版次 2026.11.15。

引用本節

格式

各種格式皆引用英文原書,本譯本即依循該原書。

每種格式都會標示本版。其連結會開啟目前版次,節標題會說明該節內文最後一次變動的時間。存取日期與擷取日期即為你開啟此頁的當日。

本頁內容

第 11 章,共 11 章: Serve the semantic layer over MCP

  1. Turn metrics into tools
  2. Carry the caller's role into every query
  3. Return answers with their provenance
  4. 在記憶體中測試伺服器
  5. Answer questions through a host
  6. 正式環境中會出什麼問題
  7. 本章做出的決定

返回頂端所有章節