Integrating External MCP Servers
Introduction: Beyond Built-In Tools
In the previous lesson, you learned how to maintain conversation context across multiple queries using session IDs. Throughout that lesson, you worked with the core query function to interact with Claude. While the Claude Agent SDK provides powerful built-in capabilities, what if you need specialized functionality for documentation search, database access, Git operations, or other domain-specific tasks? This is where MCP (Model Context Protocol) servers come in — external packages that extend your agent with pre-built tools. In this lesson, you'll learn how to connect these powerful external servers to your agent with minimal setup.
What Are MCP Servers
MCP servers are packages of pre-built tools that extend your agent's capabilities beyond the built-in options. Think of them as plugins or extensions that provide specialized functionality. For example, the Context7 MCP server provides tools for searching documentation across thousands of libraries, while other MCP servers might offer database access, Git operations, or custom business logic specific to your organization.
Each MCP server runs as a separate process that communicates with your agent through a standardized protocol. The server exposes one or more tools, and your agent can call those tools just as it calls any other available tools. The key difference is that MCP servers are external packages you connect to your agent, rather than functionality that comes pre-installed with the SDK. This architecture means you can add new capabilities to your agent without modifying the SDK itself, and you can leverage tools built by the community or your own team. The Model Context Protocol defines how your agent communicates with these external servers, handling the details of sending tool requests, receiving results, and managing the connection lifecycle.
Declaring an MCP Server Configuration
To connect an MCP server, you need to declare a configuration object that tells the SDK how to run that server. The configuration specifies the communication type, the command to execute, and any arguments needed to start the server process.
The configuration object contains three key fields. The type field specifies how your agent will communicate with the server — the value "stdio" means the server will communicate through standard input and output streams, which is the most common approach for MCP servers. The command field specifies the executable to run. In this example, "npx" is a Node.js package runner that can execute npm packages directly without installing them globally. The args field provides an array of arguments to pass to the command. Here, ["-y", "@upstash/context7-mcp"] tells npx to automatically confirm any prompts and run the Context7 MCP server package. When your agent starts, the SDK will execute this command, establish a communication channel through stdin/stdout, and keep the server process running for the duration of your agent's session.
Connecting Servers via mcpServers
Once you've declared a server configuration, you connect it to your agent by passing it to the Options object through the mcpServers parameter.
The mcpServers parameter takes an object mapping server names to configurations. In this example, we're connecting one server with the name "context7" using the configuration we declared earlier. The server name you choose here is important because it becomes part of the tool naming scheme you'll use in the next step. You can connect multiple servers by adding more entries to this object, each with its own unique name and configuration. At this point, the server is connected and its tools are available, but your agent can't use them yet because you haven't explicitly granted permission.
Whitelisting MCP Tools
Connecting an MCP server makes its tools available, but for security and control, you must explicitly whitelist which tools your agent can actually use. You do this through the allowedTools parameter using a specific naming format that identifies both the server and the tool.
The allowedTools array uses a special naming format for MCP tools: mcp__<server_key>__<tool_name>. The prefix mcp__ indicates this is an MCP tool rather than a built-in tool. The <server_key> matches the name you gave the server in the mcpServers object (in this case, "context7"). The <tool_name> is the actual tool name as defined by the MCP server. For the Context7 server, two tools are available: resolve-library-id searches for libraries by name and returns their identifiers, while get-library-docs retrieves documentation for a specific library. This explicit whitelisting approach gives you fine-grained control over which external capabilities your agent can access, which is particularly important for security and cost management.
Guiding Claude to Use MCP Tools
With the server connected and tools whitelisted, your agent can now use those tools, but you need to guide it through your prompts. The agent won't automatically know when to use MCP tools versus other available tools, so your prompt should clearly indicate what you want the agent to do and which tools are relevant.
The prompt explicitly mentions "Using the context7 tools" to guide the agent toward the MCP tools you've connected. This explicit guidance helps the agent understand that you want it to use the external documentation search capabilities. When the agent processes this prompt, it will recognize that it has access to Context7 tools (because they're in the allowedTools list), understand from your prompt that you want it to use those tools, and then call them appropriately. The query function returns a stream that you can process with helper functions like displayResponse to see the agent's responses and tool calls in real time.
Complete Example: Setting Up the Configuration
Let's examine a complete working example that connects the Context7 MCP server, whitelists its tools, and uses them to search for documentation. We'll start by looking at how to set up the complete configuration.
The example follows a clear two-step pattern for configuration. First, it declares the Context7 server configuration with the stdio communication type and the npx command to run the server. Second, it creates an Options object that connects the server through mcpServers, whitelists the two Context7 tools through allowedTools, and sets other familiar options like model and maxTurns. This configuration makes the external documentation search tools available to your agent while maintaining a clean, functional approach.
Complete Example: Running the Agent
With the configuration in place, the final step is to call the query function with a prompt that guides the agent to use the MCP tools, and then process the resulting stream.
The code calls the query function with a prompt that explicitly guides the agent to use the Context7 tools, passing in the options object that contains the MCP server configuration. The query function returns a stream of responses that you can process with the displayResponse utility function. The prompt clearly indicates that the agent should use the external documentation search capabilities to find and summarize information about MCP servers in the Claude Agent SDK. When you run this code, the agent demonstrates sophisticated multi-step reasoning using the external MCP tools.
Observing the Agent's Plan and First Tool Call
When you run the complete example, the agent begins by explaining its plan and making the first tool call to search for the relevant documentation.
The agent starts by stating its intent — it will look for documentation on how the Claude Agent SDK uses MCP servers. It then makes its first tool call to mcp__context7__resolve-library-id to locate the most relevant library. Notice how the tool name mcp__context7__resolve-library-id follows the mcp__<server_key>__<tool_name> format you configured in allowedTools, clearly identifying this as an MCP tool from the "context7" server.
Observing the First Documentation Retrieval
After resolving the relevant library, the agent proceeds to fetch documentation from multiple sources.
Here, the agent interprets the search results, determines that multiple libraries are relevant for MCP server integration, and then calls mcp__context7__get-library-docs twice to retrieve documentation from both sources. The agent uses the information returned by resolve-library-id to drive its next tool calls, showing how it chains MCP tool calls together and makes multiple parallel requests to gather comprehensive information.
Observing the Final Summary
After collecting the necessary documentation, the agent synthesizes the information into a structured summary.
The agent pulls together everything it learned from the MCP tool calls into a concise, well-structured explanation. It reinforces the configuration concepts you implemented in the code (like mcpServers and allowedTools), and connects them to broader architectural patterns such as in-process vs. external MCP servers and different communication protocols (stdio, HTTP, SSE). The summary demonstrates how the agent can synthesize information from multiple documentation sources into a coherent explanation.
Summary: Ready for Hands-On Practice
You've now learned how to expand your agent's capabilities by integrating external MCP servers. By declaring server configurations, connecting them through mcpServers, whitelisting tools with the mcp__<server_key>__<tool_name> format, and guiding your agent through clear prompts, you can give Claude access to rich, pre-built functionality with minimal setup. The functional approach using the query function makes it straightforward to configure and use MCP servers in your TypeScript applications. In the upcoming practice exercises, you'll apply these concepts by integrating different MCP servers into your own agents and building applications that leverage both built-in and external capabilities to solve real-world problems.
