Connect External Tools
What You Will Learn
In this lesson, 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 Lesson 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 Lesson 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.
Your First MCP Server
Two commands:
openclaw config set mcp.servers.time '{"command":"uvx","args":["mcp-server-time"]}'
openclaw gateway restart
Verify It Connected
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:
openclaw mcp list
This shows all configured MCP servers. You should see time in the list.
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.
Use It
Now ask your agent:
What time is it in Tokyo right now?
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:
| Tool | What It Does |
|---|---|
get_current_time | Takes a timezone, returns the current time and DST status |
convert_time | Takes a source timezone, a time, and a target timezone; returns the converted time |
Both use IANA timezone format: Asia/Tokyo, America/New_York, Europe/London.
What Just Happened
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.
Managing MCP Servers
The MCP CLI gives you commands to manage your servers:
openclaw mcp list # See all configured MCP servers
openclaw mcp show time # See details for one server
openclaw mcp set time '{"command":"uvx","args":["mcp-server-time"]}' # Add or update
openclaw mcp unset time # Remove a server
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.
When It Breaks Silently
Change the config to use a package that does not exist:
openclaw config set mcp.servers.time '{"command":"uvx","args":["this-server-does-not-exist"]}'
openclaw gateway restart
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. Stream the gateway log:
openclaw logs --follow
OpenClaw writes today's events to /tmp/openclaw/openclaw-YYYY-MM-DD.log (rotated daily), and --follow tails that file. The log shows the error: a non-zero exit code from the failed server. Press Ctrl+C once you have seen it. The agent never knew the tools existed because the server never started.
| Common Cause | What the Log Shows | Fix |
|---|---|---|
| Wrong package name | Non-zero exit code | Verify the exact package name |
| Missing runtime | "uvx: command not found" or "npx: command not found" | Install uv or Node.js |
| Remote server unreachable | Connection timeout | Verify the URL is correct and the server is running |
| Gateway not restarted | Old config still active | Run openclaw gateway restart |
By this point in the chapter, checking the log should be your first reaction. Revert with the correct package name before continuing:
openclaw config set mcp.servers.time '{"command":"uvx","args":["mcp-server-time"]}'
openclaw gateway restart
What If the Server Is Remote?
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:
| Your Server | Transport | Config Key |
|---|---|---|
| Local (npm package, Python script) | stdio | command + args |
| Remote (HTTP Server-Sent Events) | SSE | url (default for URL-based config) |
| Remote (HTTP streaming) | streamable-http | url + "transport":"streamable-http" |
Connect a remote server the same way you connected the time server, but with a URL:
openclaw mcp set remote-tools '{"url":"https://mcp.example.com"}'
openclaw gateway restart
That uses SSE by default. For streamable-http, add the transport field:
openclaw mcp set streaming-tools '{"url":"https://mcp.example.com/stream","transport":"streamable-http"}'
Both remote transports support auth headers and connection timeouts. You will connect a remote MCP server in Chapter 57.
Try With AI
Exercise 1: Add a Second MCP Server
The pattern scales. Pick a server that is useful to you and add it:
openclaw config set mcp.servers.context7 '{"command":"npx","args":["-y","@upstash/context7-mcp"]}'
openclaw gateway restart
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.
Exercise 2: Scope a Server to One Agent
Gateway-level config shares tools across all agents. Workspace-level config scopes tools to one agent. Move the time server from gateway to workspace:
openclaw config unset mcp.servers.time
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 Lesson 11, 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.
Exercise 3: Find the MCP Server List
Ask your agent:
What MCP servers are currently connected? List each server and its tools.
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.
What You Should Remember
MCP in One Sentence
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.
Silent Failure
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.
Two Config Levels
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.
Three Transports
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."