In this chapter, you will connect your first MCP server and encounter OpenClaw's most counterintuitive behavior: silent failure.
By the end, you should be able to configure an MCP server with one command, diagnose a failure that produces no error in chat (only in the gateway log), and explain the difference between workspace-level config (scoped to one agent) and gateway-level config (shared across all agents). You will also learn the three transport options: stdio for local servers, SSE and streamable-http for remote ones.
MCP is the "external access" column from Module 9.1, Chapter 6's decision tree. Now you connect one for real.
James was planning a client meeting in Tokyo. He messaged his agent on WhatsApp: "What time is it in Tokyo right now?"
The agent replied with a textbook answer about UTC offsets. Training data, not a live lookup.
"Okay, let me think about this." James pulled up his notes from Module 9.1, Chapter 6. Skills, MCP servers, plugins. "The agent already knows what timezones are. It doesn't need more knowledge. It needs access to something that actually checks a clock." He paused. "That's not a skill. MCP server?"
Emma looked up from her laptop. "Why not a plugin?"
"A plugin changes the gateway itself. I just want to connect a clock." He leaned back. "That's like when we added the freight carrier's rate API to the shipping dashboard at my old company. We didn't rewrite the dashboard. We connected an external service."
"Good." Emma went back to her screen. "There is a time server. No API key. Four lines of config. Go connect it."
You are doing exactly what James is doing. Your agent knows about timezones from its training, but it cannot check the current time. You are about to give it that ability with a single command.
Two commands:
Check the dashboard. Open Agents → Tools and look for the time server's tools: get_current_time and convert_time. If they appear, the MCP server connected successfully.
From the terminal, you can also run:
This shows all configured MCP servers. You should see time in the list.
Skills vs MCP Tools
If you ask your agent "What tools do you have?", it may list its skills (like weather, clawhub, coding-agent) but not its MCP tools. Skills and MCP tools are different: skills are loaded from SKILL.md files, MCP tools come from running server processes. The dashboard → Agents → Tools tab shows both, clearly separated. Use the dashboard to verify MCP tools, not the chat.
Now ask your agent:
The answer should be a specific, live time (not a generic "UTC+9" rule). That is a real tool call, not training data. Check the dashboard: you will see a tool badge showing the agent used get_current_time. The time server provides two tools:
Both use IANA timezone format: Asia/Tokyo, America/New_York, ইউরোপ/Лονδίνο-> Europe/London.
Wait, the prompt says "Both use IANA timezone format: Asia/Tokyo, America/New_York, Europe/London."
The gateway read your config on startup, spawned mcp-server-time as a child process, and the server registered its two tools. When the agent needed timezone information, the gateway routed the request to the time server. The agent gained new tools without any code.
The MCP CLI gives you commands to manage your servers:
These are equivalent to openclaw config set mcp.servers.* but shorter. All MCP server configs are stored centrally in openclaw.json under mcp.servers. Every agent on the gateway gets access to these tools.
Change the config to use a package that does not exist:
Ask "What time is it in Tokyo?" The agent answers from training data (the UTC+9 response again). No error in chat. No indication anything failed.
Check the dashboard: no time tools listed. Check the gateway log:
The log shows the error: a non-zero exit code from the failed server. The agent never knew the tools existed because the server never started.
By this point in the chapter, checking the log should be your first reaction. Revert with the correct package name before continuing:
Everything so far used stdio transport: the gateway spawned the server as a local child process. Remote servers use a URL instead. OpenClaw supports three transports:
Connect a remote server the same way you connected the time server, but with a URL:
That uses SSE by default. For streamable-http, add the transport field:
Both remote transports support auth headers and connection timeouts. You will connect a remote MCP server in Module 9.2.
The pattern scales. Pick a server that is useful to you and add it:
Ask your agent a documentation question: "Look up the FastAPI documentation for creating route handlers." Check the dashboard: you should see tools from both the time server and context7. Two config set commands, two independent tool sets.
What you are learning: MCP servers are additive. Each config set adds tools without affecting existing ones. Your agent's toolbox grows with every server you connect.
Gateway-level config shares tools across all agents. Workspace-level config scopes tools to one agent. Move the time server from gateway to workspace:
Now add it to your workspace's .mcp.json file instead. Create or edit ~/.openclaw/workspace/.mcp.json and add the time server config there. Restart the gateway.
Check the dashboard: your main agent should still see the time tools. When you add a second agent in Module 9.1, Chapter 10, that agent will not see them because the config lives in your workspace, not the gateway.
What you are learning: The difference between gateway-level and workspace-level config. Gateway shares tools across all agents; workspace scopes them to the agent whose workspace contains the .mcp.json file.
Ask your agent:
Compare the agent's answer with what the dashboard shows. If they match, your mental model of the MCP system is correct. If they differ, check the gateway log for servers that failed silently.
What you are learning: Your agent can report its own tool inventory. This is the fastest way to verify MCP configuration without touching the terminal.
An MCP server gives your agent access to external tools without writing code. One config command, one gateway restart, new tools appear in the dashboard.
MCP failures produce no error in chat. The agent responds normally, just without the expected tools. The gateway log is the only diagnostic. This is the most counterintuitive behavior in OpenClaw: everything looks fine, but the tools are missing.
Gateway-level (openclaw config set mcp.servers.*) shares tools across all agents. Workspace-level (.mcp.json in the workspace directory) scopes tools to one agent. Use workspace-level when agents need different tool sets.
Use command + args for local MCP servers (spawns a process). Use url with SSE or streamable-http for remote servers. If the server runs on your machine, use stdio. If it runs elsewhere, use a URL.
When Emma looked over, James had the gateway log open alongside his WhatsApp. "That silent failure caught me for about ten seconds," he said. "Then I checked the log."
"Ten seconds." Emma raised an eyebrow. "I spent twenty minutes on my first one. Kept restarting the gateway, thinking it was a config syntax problem. The actual cause was a typo in the package name. Twenty minutes because I did not check the one place that had the answer." She shrugged. "The log is always the first place to look. I learned that the slow way."
"You know what reminded me? At my old company, when the shipping system went quiet, everyone assumed it was working. Nobody checked the logs until a customer complained." He pointed at his terminal. "Two commands. I just gave my AI employee access to an external tool. No code."
James leaned back. "Skills: knowledge. MCP servers: external access. Plugins: gateway capabilities. And now I have actually connected one." He paused. "But the agent still waits for me to ask. At my old company, the good coordinator checked the supplier inbox before the morning meeting. This thing checks the clock when I tell it to."
"What if it checked on its own?" Emma said. "Not waiting for you. Acting on a schedule."