AI Agent

What Is MCP ? A Beginner's Guide to the Open Standard for AI Agents

· 7 min read · YayaAgent Team

Every AI agent needs a way to reach beyond its own model — to read a file, query a database, call an API, or search the web. Before MCP, every tool integration was custom: the agent framework wrote its own connector, its own schema, its own auth flow. Switch frameworks and you rebuild everything from scratch. MCP fixes that. It's a single open protocol — think of it as USB-C for AI agents — that defines how any model talks to any tool, so one integration works everywhere.

This guide explains what MCP actually is, how it works under the hood, and how to use it with the two frameworks covered on this site: OpenClaw and Hermes.

Before diving in, two things worth having under your belt:

Quick Decision Guide

Question Answer
What problem does MCP solve? Tool integrations are rebuilt from scratch for every framework — MCP makes them portable
Do I need MCP to use an AI agent? No — agents work fine with built-in tools. MCP adds access to a growing ecosystem of third-party connectors
Is MCP a replacement for APIs? No — it's a protocol for using APIs. The underlying service still needs an API
Which frameworks support MCP? OpenClaw, Hermes, Claude Desktop, Cursor, and most major agent frameworks as of 2026
Do I need to run my own MCP server? Only if you're connecting to a private data source. Public MCP servers (filesystem, web search, GitHub) are available as installable packages

1. The Problem MCP Solves

Before MCP, connecting an AI agent to an external tool looked like this:

  1. Framework A writes a custom "GitHub tool" — its own function signature, its own auth handling, its own error format.
  2. Framework B writes a completely different "GitHub tool" — different signature, different auth, different errors.
  3. Framework C does the same thing again.
  4. A developer who switches from Framework A to Framework B loses their GitHub integration entirely and starts over.

This is the same problem USB solved for peripherals. Before USB, every printer had its own connector type, every mouse had its own cable standard. USB didn't change what printers or mice do — it standardized how they connect.

MCP does the same thing for AI agents and external tools. It defines:

  • How the agent (the "client") discovers what tools are available — a capability handshake, not a hardcoded list.
  • How the agent calls a tool — a consistent JSON-RPC 2.0 message format.
  • How the tool responds — a structured result or error, the same shape regardless of which tool or which framework called it.
  • How auth and permissions are handled — the tool owner controls access, not the agent framework.

The result: write one MCP server for GitHub, and it works with OpenClaw, Hermes, Claude Desktop, Cursor, and any other MCP-compatible client. No rewrites.

2. How MCP Actually Works

MCP uses a client-server architecture with two roles:

Role What it does Example
MCP Client The AI agent or app that needs external tools OpenClaw, Hermes, Claude Desktop
MCP Server A small program that exposes a specific tool or data source A filesystem server, a GitHub server, a Postgres server

The communication flow:

Agent (MCP Client)  ←→  MCP Protocol (JSON-RPC 2.0)  ←→  MCP Server  ←→  External Service

The handshake happens first. When the client connects to a server, they exchange capabilities: the server says "I can do X, Y, Z" and the client says "I need A, B, C." This is dynamic — add a new MCP server and the agent automatically discovers new tools without a code change.

The transport is how the messages actually move. MCP supports two:

  • stdio — the server runs as a local subprocess, communicating over standard input/output. Fast, simple, no network. This is the default for local tools like filesystem access.
  • Streamable HTTP — the server runs as an independent remote service, communicating over HTTP. The client and server exchange messages through a single HTTP endpoint, which can optionally upgrade to a stream for longer-running responses. This is the current standard transport for hosted tools or when the server runs on a different machine. (An older two-endpoint HTTP+SSE transport served this role before 2025; it's deprecated, and most clients are dropping support for it through 2026, so new setups should use Streamable HTTP.)

For most setups, stdio is what you'll use. It's the simplest option and covers local tools — file access, local databases, command-line utilities — without any network configuration.

3. What an MCP Server Actually Looks Like

An MCP server is a small program that exposes one or more "tools" — typed functions the agent can call. Here's what a minimal filesystem MCP server exposes:

Tool Name What it does Input
read_file Read the contents of a file path (string)
write_file Write content to a file path (string), content (string)
list_directory List files in a directory path (string)

The agent doesn't need to know how the server implements these — it just sees the tool names, descriptions, and input schemas. The server handles the actual file operations, including any permission checks or sandboxing.

This is the key insight: MCP separates the interface from the implementation. The agent knows what tools are available and how to call them. The server knows how to actually do the work. Neither side needs to know the other's internals.

4. Using MCP with OpenClaw

OpenClaw has native MCP client support built in. To add an MCP server, edit ~/.openclaw/openclaw.json:

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

Each server entry specifies:

  • command — what to run (usually npx for Node.js-based servers).
  • args — the arguments passed to the command.
  • env (optional) — environment variables the server needs, like API keys.

(Field names above match OpenClaw's MCP config at the time of writing — double-check against your installed version if something doesn't load.)

After editing, validate and restart:

openclaw config validate
openclaw restart

The agent now has access to every tool those servers expose — no code changes, no custom integration. Add a Postgres server entry and the agent can query your database. Add a Slack server and it can send messages. The protocol handles the rest.

For more on how OpenClaw handles file access natively (without MCP), see how to connect AI agents to local files.

5. Using MCP with Hermes

Hermes also supports MCP natively. The configuration lives in ~/.hermes/config.yaml:

mcp:
  servers:
    filesystem:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/path/to/allowed/dir"
    github:
      command: npx
      args:
        - "-y"
        - "@modelcontextprotocol/server-github"
      env:
        GITHUB_PERSONAL_ACCESS_TOKEN: ghp_your_token_here

The structure is the same as OpenClaw — each server gets a name, a command, arguments, and optional environment variables. Hermes discovers the tools automatically on next session start.

To verify what MCP tools are available in a session:

hermes tools

This shows all enabled toolsets, including any MCP servers that connected successfully. If a server fails to start (missing dependency, bad API key), the error surfaces here rather than silently failing.

6. Where to Find MCP Servers

The MCP ecosystem is growing fast. The main hub is the official MCP servers repository on GitHub, which includes reference implementations for:

  • Filesystem — read/write/list local files
  • GitHub — repos, issues, pull requests, search
  • Postgres — query a PostgreSQL database
  • SQLite — query a local SQLite database
  • Web Search — Brave Search integration
  • Puppeteer — browser automation
  • Memory — a simple key-value memory store

Community-maintained servers cover hundreds of additional services — Slack, Notion, Google Drive, Jira, and more. Search the repository or check mcpservers.org for a curated list.

When evaluating an MCP server, check three things before adding it:

  1. Does it run locally or require a hosted service? Local is simpler; hosted may need an API key or account.
  2. What permissions does it need? A filesystem server needs a directory path — make sure it's scoped to what you actually want the agent to access, not your entire drive.
  3. Is it actively maintained? The ecosystem is young. Check the last commit date and open issues before relying on it for production workflows.

7. MCP vs. Built-In Tools: When to Use Each

MCP works as an extension mechanism on top of an agent's built-in tools, not a replacement for them. Here's how to think about the boundary:

Scenario Use
The agent already has a built-in tool for the job Built-in tool — less setup, tighter integration
You need to connect to a service the agent doesn't natively support MCP server
You want the same integration to work across multiple agent frameworks MCP server — write once, use everywhere
You need to connect to a private or internal API MCP server — wrap your API in a custom server
The task is simple and one-off Built-in tool or a quick script — MCP is overkill

For example: OpenClaw and Hermes both ship with built-in web search and file access tools. If those cover your needs, there's no reason to add an MCP server for the same thing. But if you need the agent to query a specific database, interact with a niche API, or use a tool that needs to work identically across both frameworks — that's where MCP earns its place.

For a deeper look at how the built-in web tools work, see how to give AI agents web access.

8. Common MCP Issues and How to Fix Them

Problem Likely Cause Fix
Server doesn't appear in tool list Server failed to start Check the command and args — run the command manually in a terminal to see the error
"Connection refused" or timeout Wrong transport or port For stdio servers, no port is needed. For remote servers using Streamable HTTP, verify the endpoint URL and that the server process is running
Tool call returns auth error Missing or invalid API key in env Double-check the environment variable name and value — some servers expect API_KEY, others expect TOKEN
Tool works in one framework but not another Different MCP client implementations Verify both frameworks are using the same MCP protocol version; check for framework-specific config quirks
Server is slow to respond Heavy operation or network latency For local stdio servers, check disk I/O. For remote servers, check network connectivity and server logs

The most common mistake: adding an MCP server to the config but forgetting to install the dependency it needs (usually Node.js for npx-based servers). If the server command fails silently, run it manually first:

npx -y @modelcontextprotocol/server-filesystem /tmp

If that errors, the config will error too. Fix the underlying issue, then restart the agent.

Bottom Line

MCP's whole value is portability: build or install a server once, and it works with any MCP-compatible client instead of being rebuilt per framework. Start with whatever tools OpenClaw or Hermes already ship with, and reach for an MCP server only when you need a connector they don't have built in, or one that has to behave identically across multiple frameworks.

Further reading: