Connect External Tools
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. Check the gateway log:
tail -20 ~/.openclaw/logs/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.
| 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 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.
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.
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."