How to Build an AI Agent with MCP Tools (2026)

What Is MCP and Why Your Agent Needs It

Model Context Protocol (MCP) is an open-source protocol created by Anthropic that standardizes how AI models connect to external tools and data sources. It uses JSON-RPC 2.0 over stdio or HTTP transports, giving any AI application a universal interface to any MCP-compatible server. One protocol, every tool. That’s the pitch — and it actually delivers.

Without MCP, giving your agent tools means hard-coding function calls, writing custom API wrappers, and rebuilding the plumbing every time you add a capability. With MCP, you add a server to a config file and your agent gains new abilities instantly. No code changes. No redeployment.

I use MCP every day. My entire operation — daily blog posts, social media automation, n8n workflow management, GitHub operations, Google Workspace access — runs through MCP servers connected to Claude Code. The protocol isn’t theoretical for me. It’s infrastructure.

Key distinction: MCP is an open standard, not proprietary to Claude. Any LLM application can implement the MCP client protocol. The specification is public at spec.modelcontextprotocol.io and SDKs exist for TypeScript, Python, Java, Kotlin, C#, and Swift.

MCP Architecture: The 3 Primitives

Every MCP server exposes up to three types of capabilities. Understanding these is the difference between building something useful and building something that confuses your agent.

1. Tools — Functions the AI Can Execute

Tools are the workhorse. They’re functions your agent can call — like API endpoints it invokes on demand. A GitHub MCP server exposes tools like create_issue, list_pull_requests, search_code. A database MCP server exposes query and execute. The agent decides when to call them based on the task.

2. Resources — Data the AI Can Read

Resources give your agent access to data without stuffing everything into the context window. A filesystem server exposes files as resources. A Notion server exposes pages. The agent can read what it needs, when it needs it, instead of receiving everything upfront.

3. Prompts — Reusable Templates

Prompts are server-provided templates that standardize how the agent approaches certain tasks. Less commonly used than tools and resources, but powerful for building consistent workflows across teams.

Primitive

What It Does

Example

When to Use

Tool

Agent calls a function

create_issue(title, body)

Actions that change state

Resource

Agent reads data

Read a Notion page

Large datasets, files, records

Prompt

Server provides a template

Code review template

Standardized workflows

Setting Up MCP Tools in Claude Code

If you’re using Claude Code, MCP integration is built in. No additional libraries. No custom client code. Just configuration.

Configuration Files

MCP servers are configured in JSON files at two levels:

• Project-level: .mcp.json in your project root — shared with your team via git
• User-level: ~/.claude/mcp.json — your personal servers across all projects

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

CLI Commands

Claude Code also lets you manage servers from the command line:

# Add a server
claude mcp add github npx -y @modelcontextprotocol/server-github

# List configured servers
claude mcp list

# Remove a server
claude mcp remove github

When Claude Code starts, it launches all configured MCP servers as child processes. Their tools appear alongside built-in tools like Read, Edit, and Bash. The agent calls them the same way — no special syntax. You approve or deny each call.

Tip: Start with the official MCP servers from github.com/modelcontextprotocol/servers. They’re well-tested and follow best practices. GitHub, filesystem, Slack, PostgreSQL, and Brave Search are solid starting points.

Building Your Own MCP Server

Pre-built servers cover common cases, but the real power is building custom servers for your specific tools and APIs. Here’s a working example in TypeScript using the official SDK.

TypeScript MCP Server (Complete Example)

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "weather-server",
  version: "1.0.0"
});

// Define a tool with typed parameters
server.tool(
  "get_weather",
  "Get current weather for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => {
    const response = await fetch(
      `https://api.weatherapi.com/v1/current.json?key=${process.env.WEATHER_API_KEY}&q=${city}`
    );
    const data = await response.json();
    return {
      content: [{
        type: "text",
        text: `${city}: ${data.current.temp_f}°F, ${data.current.condition.text}`
      }]
    };
  }
);

// Define a resource
server.resource(
  "weather://forecast/{city}",
  "3-day forecast for a city",
  async (uri) => {
    const city = uri.pathname.split("/").pop();
    // ... fetch forecast data
    return {
      contents: [{
        uri: uri.toString(),
        mimeType: "application/json",
        text: JSON.stringify(forecastData)
      }]
    };
  }
);

// Connect via stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

Python MCP Server

The Python SDK (mcp package) follows the same pattern:

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("my-server")

@server.tool()
async def query_database(sql: str) -> str:
    """Execute a read-only SQL query against the analytics database."""
    result = await db.execute(sql)
    return json.dumps(result, indent=2)

async def main():
    async with stdio_server() as (read, write):
        await server.run(read, write)

asyncio.run(main())

Both SDKs handle the JSON-RPC protocol, transport layer, and message framing. You write the tool logic. The SDK handles everything else.

Production Patterns: How I Use MCP

My production stack runs 6+ MCP servers simultaneously. Here’s what actually works at scale.

The Multi-Server Agent

My daily workflow connects MCP servers for GitHub, n8n workflow automation, Google Workspace, Notion, Stripe, and Firecrawl. Each handles one domain. The agent orchestrates between them.

The key insight: MCP turns “what tools does my agent have?” from a code question into a configuration question. Add a new server to the config, restart, and your agent gains new capabilities. No deployment. No code review. Just a JSON entry.

When to Build vs. When to Use Pre-Built

Scenario

Build Custom

Use Pre-Built

Internal API access

Yes — only you know your API

No

GitHub, Slack, databases

Only if you need custom behavior

Yes — use official servers

Domain-specific logic

Yes — encode your business rules

No

Standard SaaS integrations

Only if no server exists

Check the registry first

7 MCP Pitfalls That Will Cost You

These are the mistakes I’ve made and seen others make. Read them before you build.

1. Over-tooling your agent. Giving an agent 50 MCP tools confuses it. The model wastes tokens parsing tool descriptions instead of working. Start with 3-5 tools for a focused task. Add more only when the agent’s responsibilities genuinely expand.
2. Ignoring permission boundaries. MCP servers run with the permissions of the process that launches them. A filesystem server can read your ~/.ssh directory. A database server can drop tables. Restrict paths, use read-only credentials, and audit tool access. In Claude Code, users approve each call — but programmatic agents may not have that gate.
3. Poor tool descriptions. The AI decides which tool to use based on the description string. “Does stuff with files” is useless. “Read the contents of a file at the given absolute path, returning the text content with line numbers” tells the agent exactly when to use it. Invest in clear descriptions — they’re the tool’s documentation for the AI.
4. Cold start latency. Every MCP server initializes when your AI application starts. Servers that open database connections, authenticate with APIs, or load heavy dependencies add seconds to startup. Profile your startup time. Lazy-initialize expensive connections.
5. Stdio buffering on macOS/Linux. Servers using stdio transport can have output buffering issues. Always flush stdout after writing responses. The TypeScript SDK handles this automatically, but custom implementations often miss it.
6. No error handling in tool implementations. A single uncaught exception in a tool handler crashes the MCP server and disconnects all tools. Wrap every tool implementation in try/catch. Return structured error messages the AI can understand and retry intelligently.
7. Skipping the schema. MCP tools accept Zod schemas (TypeScript) or Pydantic models (Python) for input validation. Skipping validation means the AI can pass garbage parameters and get cryptic errors instead of clear rejection messages. Always validate inputs.

Building an Agent Workspace with MCP Tools

An agent workspace is the complete environment your AI agent operates in: its system prompt, its tools (MCP servers), its memory, and its skills. MCP tools are one piece of a larger architecture.

The Agent Architect helps you design this workspace from scratch — defining which MCP servers your agent needs, how they interact, and what the system prompt should say about each tool. It’s free to use and generates a complete CLAUDE.md configuration with MCP server recommendations based on your use case.

If you want the complete workspace pre-built — with working MCP configurations, skills, memory systems, and operational loops — the Full Workspace Builder ($17) ships everything. MCP config included.

MCP Tools + Automation Pipelines

MCP gets really powerful when you combine it with workflow automation. In my stack, n8n handles the scheduling and orchestration layer while MCP servers give the AI agent direct tool access.

The pattern: n8n triggers workflows on a schedule or webhook. The workflow calls Claude with MCP tools available. Claude does the complex reasoning — deciding what to research, what to write, which APIs to call. n8n handles the plumbing — posting results, sending emails, updating databases.

This is how my automated social media pipeline works. n8n fires at scheduled times. Claude reads the content queue, generates images via Galaxy AI, and posts through Buffer. The MCP servers (GitHub, Google Workspace) provide the context the agent needs to make decisions.

Warning: MCP servers in automated pipelines run without human approval gates. Every tool call executes automatically. This is powerful but dangerous. Use read-only credentials where possible, restrict file paths, and add validation in your tool implementations. The agent will call whatever you give it access to.

Resources and Next Steps

• Model Context Protocol — Official Site
• MCP Specification
• Official MCP Server Repository
• How to Build an AI Agent with Claude — the full agent-building guide
• How to Build AI Agent Skills — adding modular capabilities
• Claude Code Setup Guide — get Claude Code running in 5 minutes
• AI Agent Security — permissions, sandboxing, and trust boundaries

Frequently Asked Questions

What is MCP (Model Context Protocol)? +

MCP is an open-source protocol created by Anthropic that standardizes how AI models connect to external tools and data sources. It uses JSON-RPC 2.0 over stdio or HTTP transports, letting any AI application communicate with any MCP-compatible server. Think of it as USB-C for AI — one standard interface for every tool.

Can MCP work with models other than Claude? +

Yes. MCP is an open standard, not proprietary to Claude or Anthropic. Any LLM application can implement the MCP client protocol to connect to MCP servers. The specification is public at spec.modelcontextprotocol.io and SDKs exist for TypeScript, Python, Java, Kotlin, C#, and Swift.

How many MCP tools should I give my AI agent? +

Start with 3-5 well-documented tools for a focused task. Giving an agent 50 tools confuses it — the model spends tokens figuring out which tool to use instead of doing the work. Curate your tool set to match the specific task. You can always add more MCP servers later as your agent’s responsibilities grow.

Is MCP secure? What permissions do MCP servers have? +

MCP servers run with the permissions of the process that launches them. A filesystem MCP server can read and write anything the user running it can access. Security boundaries must be configured explicitly — use environment variables for API keys, restrict file paths, and audit which tools your agent can access. In Claude Code, users approve or deny each MCP tool call.

What’s the difference between MCP tools, resources, and prompts? +

MCP servers expose three primitives: Tools are functions the AI can execute (like API calls), Resources are data the AI can read (like files or database records), and Prompts are reusable prompt templates the server provides. Most agents primarily use tools, but resources are powerful for giving agents access to large datasets without stuffing them into the context window.