# Connect External Tools (/docs/meet-your-personal-ai-employee/07-connect-external-tools) --- type: Document title: "Connect External Tools" description: "Configure the mcp-server-time MCP server with one command, learn gateway-level versus workspace-level config, master the silent failure pattern, and understand the three transport options (stdio for local, SSE and streamable-http for remote)." status: stable order: 9607 chapter: 56 lesson: 7 duration_minutes: 25 generated: by: ag-archive/0.1.0 at: 2026-08-26T00:00:00Z ksor: audience: [public] approval: by: ag-archive/0.1.0 at: 2026-08-26T00:00:00Z trust_tier: unverified build_id: sha256:c8912c3008ae345a7fdc33ace656531ad74f37c065177057c390c7d759f1e970 source_commit: dad4758bb59919c7b9130444778ade062a2dce3e ksor_version: 0.0.47 --- ## 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: ```bash 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: ```bash openclaw mcp list ``` This shows all configured MCP servers. You should see `time` in the list. > [!NOTE] > **[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. ### 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](https://docs.openclaw.ai/cli/mcp) gives you commands to manage your servers: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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." ## Flashcards Study Aid