Model Context Protocol (MCP) for AI agents: a complete guide

Model Context Protocol is the most important thing that happened to AI agent tooling in 2024–2025. If you build agents and haven’t internalized it yet, this is the explainer.

Why it exists

Before MCP, every framework had its own tool format. LangChain tools, AutoGen tools, OpenAI function calls, Anthropic tool use schema. Building a “filesystem tool” meant writing it once per framework.

MCP says: the tool is a server. It runs as its own process (or HTTP service). It speaks JSON-RPC. Any framework with an MCP client can use it.

The result: in late 2025, you could install one filesystem MCP server and use it from Claude Desktop, Cursor, Cline, Continue, and your custom Agentmatic agent — without writing any per-framework adapter code.

The architecture

Three things:

1. A server that exposes tools. Examples: @modelcontextprotocol/server-filesystem (Node), mcp-server-git (Python), @modelcontextprotocol/server-postgres (Node), @modelcontextprotocol/server-puppeteer (browser automation).
2. A client that connects to the server. Examples: Claude Desktop, Cursor, your Agentmatic agent.
3. A transport. stdio (subprocess), SSE (HTTP), or streamable HTTP.

The protocol is JSON-RPC 2.0. Initialize, list_tools, call_tool, plus a few introspection methods.

What MCP servers exist today

A non-exhaustive list of useful, actively maintained ones:

• Filesystem — read/write/list a directory tree.
• Git — clone, commit, diff, log against a repo.
• GitHub — issues, PRs, files via the GitHub API.
• Postgres — query a database, with safe read-only mode.
• Puppeteer — browser automation.
• Slack — read/post messages.
• Memory — durable key-value memory across sessions.
• Brave Search — web search.
• Time — current time, time zones (yes really, LLMs are bad at this).
• Sentry — fetch error data.

Most are on github.com/modelcontextprotocol/servers. There are 100+ community-maintained ones.

Connecting from your agent

from agentmatic.tools.mcp import MCPClient
from agentmatic.prebuilt import create_react_agent
from agentmatic import OpenAI

# Stdio: server runs as subprocess.
fs = MCPClient.stdio([
    "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"
])

# SSE / HTTP: server is a remote service.
postgres = MCPClient.sse("https://mcp-pg.internal/sse")

tools = (await fs.list_tools_as_agentmatic()) + (await postgres.list_tools_as_agentmatic())
agent = create_react_agent(llm=OpenAI(), tools=tools)

list_tools_as_agentmatic() wraps each MCP tool as a native Agentmatic tool. No additional glue.

Reading mcp.json

If you already have an mcp.json for Claude Desktop / Cursor, Agentmatic reads the same file:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/Users/me/projects"]
    }
  }
}

from agentmatic.tools.mcp import discover_from_config

clients = await discover_from_config()  # reads ~/.mcp/mcp.json
tools = await asyncio.gather(*[c.list_tools_as_agentmatic() for c in clients.values()])

Shipping your own MCP server

Wrap any Agentmatic tool registry as an MCP server:

from agentmatic.tools.mcp import serve_mcp
from my_tools import calculator, run_query

if __name__ == "__main__":
    serve_mcp([calculator, run_query], transport="stdio")

Your tools are now usable from any MCP-compatible client. Publish the install command (uvx your-package or npx your-package) and Cursor / Claude Desktop / Cline users get one-line install.

Security: the part nobody mentions

MCP servers run in their own process with whatever permissions you give them. If you connect a filesystem MCP server with root access, the LLM can write anywhere.

Reasonable defaults:

• Filesystem — scope to a single project directory.
• Git — scope to a single repo.
• Postgres — connect as a read-only user; don’t expose write access.
• Shell — don’t. Or use Rhai / sandboxed scripting.

For sensitive tools, gate behind interrupt_before in your agent so a human approves the call.

Transports compared

Transport	When	Pros	Cons
stdio	Local servers, dev	Simple, no auth	Per-client subprocess, no remote
SSE	Remote servers	Works over HTTP, multi-client	Older spec; deprecation candidate
Streamable HTTP	New remote standard	Multi-client, modern	Less tooling coverage

For local dev: stdio. For internal services: streamable HTTP (or SSE if your client doesn’t support streamable yet).

When NOT to use MCP

• Fast in-process logic. Sub-millisecond tools (parse JSON, look up a constant) — keep them in-process.
• Tight integration with your framework’s lifecycle. A tool that needs your DI container is easier in-process.
• Streaming results back to the model mid-call. MCP’s call_tool is request/response; streaming partial results during a single tool call isn’t well-supported yet.

What’s next for MCP

• Streaming Tool Results in the spec — partial results during a long tool call.
• OAuth for HTTP servers — currently most use bearer tokens or no auth.
• Server discovery — a registry similar to npm / PyPI.

If you’re shipping AI agents in 2026 you should be MCP-aware. The ecosystem effects are real: write a tool once as an MCP server, use it everywhere.