Connect Botie to Tools with MCP

The maintenance team now uses Botie in a web app and in an internal support tool. Both need the same manual lookup, but each integration describes and calls it differently. Maintaining two copies makes it easy for their behaviour to drift.

A shared protocol can describe what a server offers and how a client requests it. Model Context Protocol, or MCP, provides that interface. We will follow a manual lookup across the connection, then see why discovering a tool does not automatically make it safe or permitted to call.

Keep the server identity attached to the tool name, check the host allowlist, then resolve the registered handler.

Maintained pump excerpts

The host is the application coordinating the user, model and available connections. An MCP client maintains a connection to a server. The server exposes capabilities such as reading maintenance records. A host can connect to several servers, each with a distinct scope and trust relationship.

That separation lets us put the manual integration beside the system that owns the manuals. The host can decide how much returned text enters a model request without moving all data ownership into the assistant.

MCP is an interface between programs. It is not itself an agent loop, a language model or a guarantee that an answer is correct.

A tool exposes an operation with named arguments, such as read_manual(asset). Tools can read or write; the word tool does not imply that every invocation changes state. A resource exposes content at an identifier such as manual://P7. A prompt supplies a reusable message template a user can choose.

These roles suggest different interfaces: a tool call, a document the application can include, or a prompt menu. They do not override permission checks. A read operation can reveal private data, and a prompt template can contain instructions the host should inspect before trusting.

The same manual service can offer several of these capabilities because they answer different application needs.

The client establishes the connection and negotiates the protocol features supported by the server. Listing tools returns descriptions and input schemas. The host can select permitted definitions to make available to a model, then send a requested name and arguments to the correct server.

A schema describes the argument shape. It does not prove that an asset belongs to the technician or that a URL is safe to fetch. The receiving service still validates both data and access. If a server paginates discovery results, the client must follow its cursor rather than assuming one page contains everything.

Keep discovery, selection and execution distinct in the trace. A tool can be listed successfully while a particular call is correctly denied.

The reference defines a tool, a fixed resource and a prompt. It then uses an in-process client to discover and call the tool without a model. That is enough to test the service interface before adding an agent that chooses calls.

The example follows the current official Python SDK 2.x API. Older tutorials often use FastMCP from mcp.server.fastmcp; do not mix imports from different major versions. Pin your resolved environment once the example works.

The result describes the fixture’s lookup. No model decides what to request in this program.

import anyio
from mcp import Client
from mcp.server import MCPServer

mcp = MCPServer("Perceptron Lab invented manuals")
MANUALS = {"P7": "Inspect the mounting and coupling."}

@mcp.tool()
def read_manual(asset: str) -> dict:
    """Read the invented excerpt for a named pump."""
    if asset not in MANUALS:
        return {"found": False, "asset": asset}
    return {"found": True, "asset": asset, "text": MANUALS[asset]}

@mcp.resource("manual://P7")
def p7_manual() -> str:
    """The invented P7 manual excerpt."""
    return MANUALS["P7"]

@mcp.prompt()
def inspection_question(asset: str) -> str:
    """Ask which inspection the supplied manual supports."""
    return f"Read the manual for {asset} and identify its inspection checks."

async def main():
    # In-process transport for a local test, with no model or network call.
    async with Client(mcp) as client:
        listed = await client.list_tools()
        assert "read_manual" in [tool.name for tool in listed.tools]
        result = await client.call_tool("read_manual", {"asset": "P7"})
        assert not result.is_error
        print(result.structured_content)

if __name__ == "__main__":
    anyio.run(main)

A completed transport request can carry a tool failure. Inspect the result’s error status before reading structured data as a success. Also distinguish an application outcome such as found = False from a failure to contact the service at all.

The returned content may include text and other content blocks. Preserve provenance when adding it to context: which server returned it, from which record, and at what revision? Text that says to change the assistant’s rules is still returned content, not new authority over the host.

The typed client API uses its documented Python field names. A raw protocol JSON payload may spell fields differently, so do not interchange the two representations by guesswork.

Suppose the maintenance service and a community-notes service both expose read_manual. If the host indexes tools only by their local name, one can accidentally replace the other. Use an unambiguous mapping from the model-visible tool to its configured connection and local name.

The workshop writes that mapping as server/tool for readability. This slash convention is our local teaching registry, not an MCP naming requirement. The allowlist uses the same qualified identity, so permitting maintenance/read_manual does not also permit community/read_manual.

If a permitted tool disappears, report it as unavailable. Quietly falling back to a similarly named tool would change the source and possibly its authority.

discovered = [
    {"server": "maintenance", "tool": "read_manual"},
    {"server": "archive", "tool": "read_manual"},
]
qualified = [item["server"] + "/" + item["tool"] for item in discovered]
print(qualified)
print(len(set(qualified)))

['maintenance/read_manual', 'archive/read_manual']
2

A server launched over standard input and output is a local program with the permissions of its process. Connecting it does not automatically confine its filesystem or network access. Review the program, its configuration and the permissions it receives.

A remote service brings another trust boundary. Imagine the maintenance server accepting a token intended for the payroll service just because the token has a valid signature. The signature tells us who issued it; we still have to check who may use it and where. An HTTP MCP server using the protocol’s authorisation scheme must validate that a token was issued for that server. It must not pass the incoming token through to a downstream API.

Keep credentials in the host or service environment. Grant the scopes needed for this job, and check object access inside the receiving service. Tool descriptions and annotations are claims from the server, not independent proof of its behaviour.

Start with a narrow read-only integration and invented fixtures. Add a write tool only after the approval and idempotency rules from the preceding lesson are enforced by the effect-owning service.

A protocol test can establish that a tool is discoverable, accepts the expected arguments and returns the expected fixture. The workshop adds a host routing check, including a same-name tool on a different server. Those are useful integration tests.

A separate agent evaluation must ask whether Botie chose the right capability and used its output correctly. Keep both layers. When a technician receives an unsupported answer, we want to distinguish a misrouted lookup from an incorrect interpretation of a correctly retrieved excerpt.

The next work is observing a complete run so we can see where a failure began, rather than judging only the final sentence.