Model Context Protocol standardizes tool access between AI hosts and external tool servers

The Model Context Protocol in Python

Introduction Every agent needs tools, and every tool needs a way to reach the model. Building Agentic Workflows in Python built that connection by hand — a hand-written JSON schema, a loop that dispatches on block.name. LLM Frameworks vs. the Raw SDK in Python showed LangChain's @tool turning a plain function into that same schema via bind_tools. Both are still bespoke: the tool lives inside one process, wired to one agent, in one language. The Model Context Protocol (MCP) solves a different problem: it standardizes the wire format between an AI application and a tool server, so the server doesn't have to be rewritten per agent, per framework, or per language. This post covers what that buys you, builds a minimal MCP server and a client that consumes it — both on the official Python SDK — and gives an honest answer to when reaching for a protocol is worth it over a direct tool call. The Problem MCP Solves Without a shared protocol, every pairing of agent framework and tool needs its own glue code: a LangChain @tool wrapper, a hand-rolled schema for the raw SDK, a different wrapper again for whatever framework a teammate picks next — an integration per framework, per tool. That's an M×N problem. MCP flattens it to M+N. A server exposes tools, resources, and prompts once, over a standard JSON-RPC protocol. Any host application — Claude Code, Claude Desktop, VS Code, or your own agent — creates an MCP client that speaks that same protocol, regardless of which framework built the host. Write the server once; every MCP-aware host can use it without new integration code. The protocol itself is intentionally boring: JSON-RPC 2.0 messages for lifecycle negotiation, tool discovery, and tool execution. Discovery (tools/list) and execution (tools/call) are the two calls that matter for this post: // tools/list response (abbreviated) { "jsonrpc": "2.0", "id": 2, "result": { "tools": [ { "name": "get_account_balance", "description": "Look up the balance for an account by ID", "inputSchema": { "type": "object", "properties": { "account_id": { "type": "string" } }, "required": ["account_id"] } } ]} } Two transports cover most cases: stdio (a local subprocess, one client per server — what this post uses) and Streamable HTTP (a remote server, many clients, standard bearer-token auth). Source: MCP architecture overview. Building a Minimal MCP Server The official Python SDK's stable line is v1.x — v2 is alpha and explicitly not recommended for production (python-sdk README), so this post pins to it: uv add "mcp[cli]" FastMCP turns a type-hinted, docstring-described function into a tool — no hand-written JSON Schema, matching the "two type-hinted functions" pitch of the SDK's own quickstart. The tool is a read-only account-balance lookup, deliberately keyed by ID rather than a free-text query, for reasons the next section makes concrete: import re from mcp.server.fastmcp import FastMCP mcp = FastMCP("accounts-server") # A fixed, in-memory dataset — stands in for a real accounts service ACCOUNTS = {"ACC-100001": 542.10, "ACC-100002": 12.50} ACCOUNT_ID = re.compile(r"^ACC-\d{6}$") @mcp.tool() def get_account_balance(account_id: str) -> str: """Look up the balance for an account by ID. Args: account_id: Account ID, e.g. ACC-100001. """ # Validate/whitelist BEFORE using — account_id is model-provided, untrusted data if not ACCOUNT_ID.match(account_id): raise ValueError("Invalid account ID format") balance = ACCOUNTS.get(account_id) return f"Balance for {account_id}: ${balance}" if balance is not None \ else f"No account found for {account_id}" A read-only resource — MCP's second primitive, for data the model can load into context without an action attached — is one more decorator: @mcp.resource("docs://refund-policy") def refund_policy() -> str: """Current refund policy text.""" return "Refunds are issued within 5 business days." if __name__ == "__main__": mcp.run(transport="stdio") # never print() here — it corrupts the JSON-RPC stream on stdio Source for FastMCP, @mcp.tool(), and @mcp.resource(): python-sdk v1.x README and the official Build an MCP Server tutorial. The stdio logging warning is language-agnostic: print() writes to stdout by default, which is the same stream the protocol uses — log to sys.stderr or a logging library instead. The Trust Boundary Doesn't Move The account_id argument a tool function receives is the same untrusted, model-provided data as block.input in the raw SDK loop (post 15) or the arguments a @tool-decorated function receives from bind_tools/create_agent (post 27) — MCP standardizes the wire format, not the trust model. FastMCP does validate the shape of arguments against the schema it derives from your type hints before your function ever runs — but shape validation only confirms account_id is a string, not that it's a safe string. The regex check above still has to happen inside the function body. Never skip that second check by trusting the type hint alone: # UNSAFE — never do this: string-interpolating a tool argument into a query sql = f"SELECT balance FROM accounts WHERE id = '{account_id}'" # SQL injection # SAFE — validate/whitelist first (as get_account_balance does above), then use a fixed # lookup or a parameterized query — never a query string built from model input The lesson from post 15's execute_validated_tool carries over unchanged: whitelist the shape you expect, reject anything else, and never let a tool argument reach a shell command, file path, or SQL string by concatenation. Building a Client That Consumes the Server A client connects over the same stdio transport, discovers the tool, and calls it — no knowledge of how the server was implemented: import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client server_params = StdioServerParameters(command="python", args=["accounts_server.py"]) async def main(): async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools = await session.list_tools() print("Available:", [t.name for t in tools.tools]) result = await session.call_tool( "get_account_balance", arguments={"account_id": "ACC-100001"}) print(result.content[0].text) asyncio.run(main()) Source for ClientSession, StdioServerParameters, stdio_client, and session.call_tool: python-sdk v1.x docs/client.md. This is the same pattern modelcontextprotocol.io's own Build an MCP Client tutorial uses — the client doesn't care which SDK or language built the server on the other end of the transport. Wiring MCP Into the Agent Loop from Post 15 The agent loop itself doesn't change — only where the tool list and tool execution come from. Instead of a hand-written TOOLS list and a local execute_validated_tool function, list tools from the MCP session and route tool_use blocks through session.call_tool(...): tools_response = await session.list_tools() anthropic_tools = [{ "name": t.name, "description": t.description, "input_schema": t.inputSchema, # already the JSON-Schema shape the Messages API expects } for t in tools_response.tools] # Inside the loop from post 15, in place of execute_validated_tool(block.name, block.input): mcp_result = await session.call_tool(block.name, block.input) text_result = mcp_result.content[0].text Everything else from post 15 — the MAX_ITERATIONS cap, claude-opus-4-8 with thinking={"type": "adaptive"}, the message bookkeeping — is unchanged. Only the tool's implementation moved to a separate, reusable process, and t.inputSchema needs no manual conversion — MCP tool schemas are already the same JSON Schema shape tools= expects. MCP vs. the Framework Tool Abstraction (Post 27) LangChain's @tool/bind_tools/create_agent (post 27) wrap a function living in your own Python process — convenient, but the tool only exists inside that one application. MCP wraps a separate process or service behind a standard protocol, so the same accounts server above can be launched by Claude Desktop, called from Claude Code, and consumed by this post's plain client — three unrelated hosts, zero rewritten integration code (the "broad ecosystem support" modelcontextprotocol.io advertises). The two aren't mutually exclusive: LangChain ships langchain-mcp-adapters, which converts an MCP session's tools directly into LangChain tools, so create_agent can drive them without a manual session.call_tool loop: from langchain_mcp_adapters.tools import load_mcp_tools from langchain.agents import create_agent async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() tools = await load_mcp_tools(session) # MCP tools -> LangChain tools agent = create_agent(model, tools) # same create_agent as post 27 Source: langchain-mcp-adapters README. Framework tool abstractions and MCP solve different layers of the same problem: one wires a function into a prompt; the other lets that function's server outlive any one framework. When MCP Earns Its Weight — and When It's Overkill Reach for MCP when the tool or data source needs to be shared across independently-built AI applications — your accounts lookup used by Claude Desktop for support staff and Claude Code for engineers and a custom internal agent — or when you're consuming someone else's server (Sentry, GitHub, a filesystem) without writing integration code per host. It's the right call when the tool is a product in its own right, not a private implementation detail of one agent. It's ceremony when the tool has exactly one caller in one codebase: a separate process, a stdio or HTTP transport, and a protocol handshake are pure overhead next to a @tool-decorated function (post 27) or a hand-written JSON schema (post 15) that never leaves the interpreter. Build the direct version first; promote it to an MCP server only once a second, independent host actually needs to call it. Practical Checklist Practice Why it matters Start with a direct tool call (post 15/27); promote to MCP only when a second host needs it MCP's cost — a process, a transport, a protocol — buys nothing for a single caller Validate/whitelist tool arguments inside the function body, even with type hints in place Type hints check shape, not safety — get_account_balance still checks the regex Never f-string a tool argument into SQL, a shell command, or a file path The same rule as posts 15/27 — MCP doesn't change the trust boundary Never print() in a stdio-transport server Corrupts the JSON-RPC stream; log to sys.stderr or a logging library instead Pin mcp<2 (or an explicit 2.0.0bN) rather than an unpinned install v2 is alpha; an unpinned upgrade could land breaking changes mid-project Cite a live source for every MCP class/function before shipping The SDK is under active development; a stale snippet is worse than none Final Thoughts MCP doesn't replace the agentic loop from post 15 or the framework tool abstractions from post 27 — it standardizes what sits behind either one: a tool server that any compliant client can discover and call, without per-host glue code. That standardization is worth real engineering cost when a tool needs to serve more than one application; for a tool with one caller, the direct approaches this series already covered remain the simpler, and correct, default.

2 hours ago

The Model Context Protocol in Java

Introduction Every agent needs tools, and every tool needs a way to reach the model. Building Agentic Workflows in Java built that connection by hand — a hand-written Tool schema, a loop that dispatches on toolUse.name(). LLM Frameworks vs. the Raw SDK in Java showed LangChain4j and Spring AI turning an annotated Java method into that same schema via reflection. Both are still bespoke: the tool lives inside one process, wired to one agent, in one language. The Model Context Protocol (MCP) solves a different problem: it standardizes the wire format between an AI application and a tool server, so the server doesn't have to be rewritten per agent, per framework, or per language. This post covers what that buys you, builds a minimal MCP server and a client that consumes it — both on the official Java SDK — and gives an honest answer to when reaching for a protocol is worth it over a direct tool call. The Problem MCP Solves Without a shared protocol, every pairing of agent framework and tool needs its own glue code: a LangChain4j tool wrapper, a Spring AI @Tool method, a hand-rolled schema for the raw SDK — three integrations for one capability, repeated for every tool and every framework you add. That's an M×N integration problem. MCP flattens it to M+N. A server exposes tools, resources, and prompts once, over a standard JSON-RPC protocol. Any host application — Claude Code, Claude Desktop, VS Code, or your own agent — creates an MCP client that speaks that same protocol, regardless of which framework built the host. Write the server once; every MCP-aware host can use it without new integration code. The protocol itself is intentionally boring: JSON-RPC 2.0 messages for lifecycle negotiation, tool discovery, and tool execution. Discovery (tools/list) and execution (tools/call) are the two calls that matter for this post: // tools/list response (abbreviated) { "jsonrpc": "2.0", "id": 2, "result": { "tools": [ { "name": "get_account_balance", "description": "Look up the balance for an account by ID", "inputSchema": { "type": "object", "properties": { "accountId": { "type": "string" } }, "required": ["accountId"] } } ]}} Two transports cover most cases: stdio (a local subprocess, one client per server — what this post uses) and Streamable HTTP (a remote server, many clients, standard bearer-token auth). Source: MCP architecture overview. Building a Minimal MCP Server The official Java SDK (io.modelcontextprotocol.sdk, Tier 2) needs no external framework — its core mcp module ships stdio and HTTP transports directly (Java MCP Server docs): <dependencyManagement> <dependencies> <dependency> <groupId>io.modelcontextprotocol.sdk</groupId> <artifactId>mcp-bom</artifactId> <version>2.0.0</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>io.modelcontextprotocol.sdk</groupId> <artifactId>mcp</artifactId> </dependency> </dependencies> The tool is a read-only account-balance lookup — deliberately simple, and deliberately keyed by ID rather than a free-text query, for reasons the next section makes concrete: import io.modelcontextprotocol.server.McpServer; import io.modelcontextprotocol.server.McpSyncServer; import io.modelcontextprotocol.server.McpServerFeatures.SyncToolSpecification; import io.modelcontextprotocol.server.transport.StdioServerTransportProvider; import io.modelcontextprotocol.json.McpJsonDefaults; import io.modelcontextprotocol.spec.McpSchema.*; import java.util.List; import java.util.Map; import java.util.regex.Pattern; // A fixed, in-memory dataset — stands in for a real accounts service private static final Map<String, Double> ACCOUNTS = Map.of( "ACC-100001", 542.10, "ACC-100002", 12.50); private static final Pattern ACCOUNT_ID = Pattern.compile("^ACC-\\d{6}$"); Map<String, Object> inputSchema = Map.of( "type", "object", "properties", Map.of("accountId", Map.of("type", "string", "description", "Account ID, e.g. ACC-100001")), "required", List.of("accountId")); SyncToolSpecification balanceTool = SyncToolSpecification.builder() .tool(Tool.builder("get_account_balance", inputSchema) .description("Look up the balance for an account by ID") .build()) .callHandler((exchange, request) -> { Object raw = request.arguments().get("accountId"); // Validate/whitelist BEFORE using — request.arguments() is model-provided, untrusted data if (!(raw instanceof String accountId) || !ACCOUNT_ID.matcher(accountId).matches()) { return CallToolResult.builder() .content(List.of(TextContent.builder("Invalid account ID format").build())) .isError(true).build(); } Double balance = ACCOUNTS.get(accountId); String text = balance != null ? "Balance for " + accountId + ": $" + balance : "No account found for " + accountId; return CallToolResult.builder().content(List.of(TextContent.builder(text).build())).build(); }) .build(); StdioServerTransportProvider transportProvider = new StdioServerTransportProvider(McpJsonDefaults.getMapper()); McpSyncServer server = McpServer.sync(transportProvider) .serverInfo("accounts-server", "1.0.0") .capabilities(ServerCapabilities.builder().tools(true).build()) .build(); server.addTool(balanceTool); A read-only resource — MCP's second primitive, for data the model can load into context without an action attached — is a few lines more: server.addResource(new McpServerFeatures.SyncResourceSpecification( Resource.builder("docs://refund-policy", "Refund Policy") .description("Current refund policy text").mimeType("text/plain").build(), (exchange, request) -> ReadResourceResult.builder(List.of(TextResourceContents.builder( "docs://refund-policy", "Refunds are issued within 5 business days.").build())).build())); Source for the tool/resource specification shapes: Java MCP Server docs. StdioServerTransportProvider communicates over stdin/stdout — never System.out.println in a stdio server; it corrupts the JSON-RPC stream (the same logging warning every language's quickstart repeats). The Trust Boundary Doesn't Move request.arguments() in a tool's call handler is the same untrusted, model-provided data as toolUse.input() in the raw SDK loop (post 14) or the arguments a @Tool-annotated method receives (post 26) — MCP standardizes the wire format, not the trust model. The SDK does validate the shape of arguments against inputSchema before your handler ever runs (a JSON Schema 2020-12 check, on by default, per the migration notes) — but shape validation only confirms accountId is a string, not that it's a safe string. The regex check above still has to happen inside the handler. Never skip that second check by trusting the schema alone: // UNSAFE — never do this: string-interpolating a tool argument into a query String sql = "SELECT balance FROM accounts WHERE id = '" + accountId + "'"; // SQL injection // SAFE — validate/whitelist first (as balanceTool does above), then use a fixed lookup // or a parameterized query — never string-built from model input The lesson from post 14's executeValidatedTool carries over unchanged: whitelist the shape you expect, reject anything else, and never let a tool argument reach a shell command, file path, or SQL string by concatenation. Building a Client That Consumes the Server A client connects over the same stdio transport, discovers the tool, and calls it — no knowledge of how the server was implemented: import io.modelcontextprotocol.client.McpClient; import io.modelcontextprotocol.client.McpSyncClient; import io.modelcontextprotocol.client.transport.ServerParameters; import io.modelcontextprotocol.client.transport.StdioClientTransport; import io.modelcontextprotocol.spec.McpSchema.*; ServerParameters params = ServerParameters.builder("java") .args("-jar", "/path/to/accounts-mcp-server.jar") .build(); var transport = new StdioClientTransport(params, McpJsonDefaults.getMapper()); McpSyncClient client = McpClient.sync(transport).build(); client.initialize(); ListToolsResult tools = client.listTools(); System.out.println("Available: " + tools.tools().stream().map(Tool::name).toList()); CallToolResult result = client.callTool( CallToolRequest.builder("get_account_balance") .arguments(Map.of("accountId", "ACC-100001")) .build()); client.closeGracefully(); Source for McpClient/ServerParameters/StdioClientTransport: Java MCP Client docs. This is the same shape modelcontextprotocol.io's own Build an MCP Server tutorial uses to test a Spring AI weather server from a plain Java client — the client doesn't care which SDK or framework built the server on the other end of the transport. Wiring MCP Into the Agent Loop from Post 14 The agent loop itself doesn't change — only where the tool list and tool execution come from. Instead of hand-written Tool objects and a local executeValidatedTool method, list tools from the MCP client and route tool_use blocks through client.callTool(...): import com.anthropic.core.JsonValue; // Convert an MCP Tool's Map-shaped inputSchema into the Anthropic SDK's Tool.InputSchema // (same InputSchema.builder() shape post 26 hand-writes for getWeatherTool/calculateTool) @SuppressWarnings("unchecked") private static com.anthropic.models.messages.Tool toAnthropicTool(Tool mcpTool) { Map<String, Object> props = (Map<String, Object>) mcpTool.inputSchema().getOrDefault("properties", Map.of()); List<String> required = (List<String>) mcpTool.inputSchema().getOrDefault("required", List.of()); var propsBuilder = com.anthropic.models.messages.Tool.InputSchema.Properties.builder(); props.forEach((name, schema) -> propsBuilder.putAdditionalProperty(name, JsonValue.from(schema))); return com.anthropic.models.messages.Tool.builder() .name(mcpTool.name()).description(mcpTool.description()) .inputSchema(com.anthropic.models.messages.Tool.InputSchema.builder() .properties(propsBuilder.build()).required(required).build()) .build(); } ListToolsResult mcpTools = client.listTools(); List<com.anthropic.models.messages.Tool> anthropicTools = mcpTools.tools().stream().map(ToolBridge::toAnthropicTool).toList(); // Inside the loop from post 14, in place of executeValidatedTool(toolUse.name(), toolUse.input()): CallToolResult mcpResult = client.callTool( CallToolRequest.builder(toolUse.name()).arguments(toolUse.input()).build()); String textResult = mcpResult.content().stream() .filter(TextContent.class::isInstance).map(c -> ((TextContent) c).text()) .findFirst().orElse(""); Everything else from post 14 — the MAX_ITERATIONS cap, claude-opus-4-8 with ThinkingConfigAdaptive, the message bookkeeping — is unchanged. Only the tool's implementation moved to a separate, reusable process. MCP vs. the Framework Tool Abstraction (Post 26) LangChain4j's @Tool/AiServices and Spring AI's @Tool/ChatClient (post 26) wrap a method living in your own JVM process — convenient, but the tool only exists inside that one application. MCP wraps a separate process or service behind a standard protocol, so the same accounts server above can be launched by Claude Desktop, called from Claude Code, and consumed by this post's plain-Java client — three unrelated hosts, zero rewritten integration code (the "broad ecosystem support" modelcontextprotocol.io advertises). The two aren't mutually exclusive: Spring AI ships its own MCP client boot starter, so a Spring Boot agent can consume this exact server as auto-configured tools instead of hand-rolling the McpClient above: <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-client</artifactId> </dependency> with spring.ai.mcp.client.stdio.servers-configuration pointing at a server-launch config — confirmed in modelcontextprotocol.io's own Build an MCP Server Java walkthrough. Framework tool abstractions and MCP solve different layers of the same problem: one wires a method into a prompt; the other lets that method's server outlive any one framework. When MCP Earns Its Weight — and When It's Overkill Reach for MCP when the tool or data source needs to be shared across independently-built AI applications — your accounts lookup used by Claude Desktop for support staff and Claude Code for engineers and a custom internal agent — or when you're consuming someone else's server (Sentry, GitHub, a filesystem) without writing integration code per host. It's the right call when the tool is a product in its own right, not a private implementation detail of one agent. It's ceremony when the tool has exactly one caller in one codebase: a separate process, a stdio or HTTP transport, and a protocol handshake are pure overhead next to a @Tool-annotated method (post 26) or a hand-written Tool schema (post 14) that never leaves the JVM. Build the direct version first; promote it to an MCP server only once a second, independent host actually needs to call it. Practical Checklist Practice Why it matters Start with a direct tool call (post 14/26); promote to MCP only when a second host needs it MCP's cost — a process, a transport, a protocol — buys nothing for a single caller Validate/whitelist request.arguments() inside the handler, even with schema validation on Schema validation checks shape, not safety — get_account_balance still checks the regex Never string-interpolate a tool argument into SQL, a shell command, or a file path The same rule as posts 14/26 — MCP doesn't change the trust boundary Never write to stdout in a stdio-transport server Corrupts the JSON-RPC stream; log to stderr or a file instead Prefer a fixed lookup or parameterized query over building a query string from model input The account-balance tool above never builds a string query from accountId Cite a live source for every MCP class/method before shipping The SDK is Tier 2 and evolving; a stale snippet is worse than none Final Thoughts MCP doesn't replace the agentic loop from post 14 or the framework tool abstractions from post 26 — it standardizes what sits behind either one: a tool server that any compliant client can discover and call, without per-host glue code. That standardization is worth real engineering cost when a tool needs to serve more than one application; for a tool with one caller, the direct approaches this series already covered remain the simpler, and correct, default.

2 hours ago