OpenClaw MCP Server: How to Add One, Step by Step (2026)

Add an OpenClaw MCP server, step by step

OpenClaw is an open-source AI agent that runs on a machine you control. You run these six steps in a terminal, the window where you type commands, on that machine. Each step has its proof, the sign that it worked, and its usual trap.

1. Find what your server needs. Search for your service's name plus "MCP server". The server's own page, usually on GitHub, tells you which of two kinds it is. A local server is a program that OpenClaw starts on its own machine, so the page gives a start command. A remote server is an address on the web, and it runs wherever its owner put it.

Bannerbear, a service that generates images from templates, offers both in its setup video of 2 November 2026. The remote one takes a single command. The local one can reach your files, to upload them for instance. That gives a way to choose: go local when the server has to touch your files.

Prefer the server the service publishes itself. A local server runs with the same rights as the Gateway on your machine, so a version from a stranger could reach whatever your agent can reach. Note any key the server's page asks for too. A key is the code that lets the server use your account.

For a first try, the MCP project publishes free sample servers. One of them, the memory server, lets your agent save facts in a file, and it needs no account and no key. The commands below use it.

2. Store its key in OpenClaw's key file. Skip this step if your server asks for no key, as the memory server doesn't. OpenClaw reads ~/.openclaw/.env when it starts, and ~ means your home folder. Add one line, with a name you choose and your key:

echo 'GITHUB_TOKEN=paste-your-key-here' >> ~/.openclaw/.env

When you add the server, you refer to the key by that name, written ${GITHUB_TOKEN}. OpenClaw's config file then holds only the name, not the key. openclaw mcp show, which prints a server's saved settings, hides the value too: it showed __OPENCLAW_REDACTED__ in the test.

A new name in that file was read at once in the test, even with the Gateway running. A new value for a name already in use is different: it only reached the server after a Gateway restart, with openclaw gateway restart.

3. Stop the Gateway. Check your version first with openclaw --version. If you didn't start the Gateway yourself in a terminal window, your system runs it in the background, and this stops it:

openclaw gateway stop

That command stopped such a Gateway in the test, on Linux. If you started yours by hand with openclaw gateway run, press Ctrl+C in its window instead.

Since 2026.10.10, every openclaw mcp command that changes a server has to be the only program using OpenClaw's data, and a running Gateway is already using it. Versions 2026.10.7 to 2026.10.9 ran openclaw mcp add with the Gateway on. On 2026.10.10, you get this message:

Cannot admit mcp.set for MCP credentials and configuration in state root /root/.openclaw:
This operation requires exclusive offline state ownership. No local mutation was attempted.

It means nothing was changed, so there is nothing to repair. Stop the Gateway and run the same command again.

One user reported on 3 November 2026 that openclaw gateway stop itself refuses on an Intel Mac, saying it can't check what started the command ("Process ancestry could not be fully inspected"). That report, issue #191944 on OpenClaw's public bug list, is still open. If you get that message, use the Settings form instead.

4. Add the server. Install the memory server once with npm, the installer that comes with Node, which OpenClaw runs on. Then give OpenClaw its start command:

npm install -g @modelcontextprotocol/server-memory
openclaw mcp add memory \
  --command mcp-server-memory \
  --env MEMORY_FILE_PATH=$HOME/agent-memory.jsonl

memory is the name you choose, and --command is the program to start. --env is a setting the server reads, here the file where it keeps its facts, and $HOME is your home folder.

OpenClaw starts the server before saving it. A server that answers gets Saved MCP server "memory", and OpenClaw writes it as mcp.servers.memory in its config file, ~/.openclaw/openclaw.json. A misspelled command was refused in the test with spawn does-not-exist ENOENT, the system's way of saying it can't find that program.

Many server pages start a server with npx -y <package>, which downloads the program and runs it in one go. OpenClaw accepts that (--command npx --arg -y --arg @modelcontextprotocol/server-memory). But OpenClaw runs one copy of a local server per conversation, and each copy then keeps an extra npm program using about 127 MB of memory. Installing once avoids it.

A server with a key needs one more option, --no-probe. During openclaw mcp add, OpenClaw tests the server with your key's name, not the key: in the test, the server received the text ${DEMO_KEY}. A server that checks its key on arrival refuses that, and nothing is saved. --no-probe skips that test, and the check in the next step runs it with the real key.

openclaw mcp add github --no-probe \
  --command github-mcp-server --arg stdio \
  --env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}'

That is GitHub's server. For another service, change these parts:

• github is the name you give the server. You choose it, short and lowercase.
• github-mcp-server is the program to start. The server's page gives it, and says how to install it.
• --arg stdio is an extra word after the program's name. The server's page shows it. Use one --arg per word, and none if there is no extra word.
• GITHUB_PERSONAL_ACCESS_TOKEN is the name the server expects. The server's page gives the name it wants for its key.
• ${GITHUB_TOKEN} is the name in your key file. Keep the ${ } and the single quotes, which stop your terminal from filling in the value.

The test ran that pattern with a small stand-in server and a fake key, because it used no GitHub account. If that looks like too much, paste this into any AI assistant:

Here is an MCP server's page: <paste its address>.
Give me the exact `openclaw mcp add` command for it, with --no-probe,
and tell me what to install first. My key is in ~/.openclaw/.env
under the name <NAME>: write it as ${<NAME>} and never ask me for the key itself.

For a remote server, give its address and its transport, the way the two sides exchange messages. Almost any server today uses Streamable HTTP:

openclaw mcp add docs \
  --url https://mcp.example.com/mcp \
  --transport streamable-http

Leave --transport out and OpenClaw falls back on SSE, an older way that the MCP standard's official text retired in March 2025. A current server then answers with an error 400, and nothing is saved. An address missing its last part, usually /mcp, failed too.

A remote server usually takes its key in a header, a line sent with each request. The server's page gives its exact form, most often Authorization: Bearer <key>:

openclaw mcp add docs --no-probe \
  --url https://mcp.example.com/mcp \
  --transport streamable-http \
  --header 'Authorization=Bearer ${DOCS_KEY}'

The test used a stand-in that refuses a wrong key. Without --no-probe, the add stopped on authentication refused (401). With it, the real key reached the server at the next check.

A remote server may sign you in with OAuth instead, a browser sign-in that gives OpenClaw an access key. Add --auth oauth, then run openclaw mcp login <name> once. That sign-in wasn't part of the test, and OpenClaw's docs warn that "Authentication saved" doesn't prove the server works.

5. Test it and start the Gateway. The first of these commands connects to the server with your real key, and it only runs while the Gateway is stopped. It should print memory: ok, and the last one should say "Connectivity check: ok":

openclaw mcp doctor memory --probe
openclaw gateway start
openclaw gateway status

If you run the Gateway by hand, use openclaw gateway run instead of start, and run the last command in a second window.

6. Try it in a conversation. Send your agent a new message, so that the server connects to that conversation. Then ask OpenClaw which tools the conversation received:

openclaw gateway call tools.effective --params '{"sessionKey":"agent:main:main"}'

agent:main:main is the main conversation of the agent named main, and OpenClaw's commands call a conversation a session. If you talk to your agent in Telegram or another app, the Key column of openclaw sessions list gives that conversation's name, to use instead.

The answer should contain a group called "MCP server tools", with your tools in it. Finally, ask your agent to use one tool that changes nothing, such as "Read your memory graph and tell me what's in it". A new memory server answers that it's empty, and that counts as a success.

Add a server while the Gateway keeps running

Stopping your agent isn't always an option, for instance when it's halfway through a job. Four other roads work, because the running Gateway applies the change itself. None of them tests the server first, so you check it afterwards.

The Settings form works in your browser. Open the Control UI, OpenClaw's admin page. openclaw dashboard opens it, and its usual address is http://127.0.0.1:18789/. First make sure only you can open that page.

Go to Settings → MCP and select Add server. Fill in a name, then pick the transport: Streamable HTTP for a web address, Stdio for a program on your machine. Then type the address, or the whole start command on one line.

A remote server added this way in the test was saved with the right settings, and the Gateway applied it at once. The form starts on Streamable HTTP, while the terminal command falls back on SSE. The form has no field for keys, so a server that needs one goes through openclaw config set.

On 2026.10.10, the + menu of a new chat in the Control UI lists your saved servers under Connectors, each with a switch for that chat. That menu doesn't add a server. OpenClaw's docs, which can run ahead of its releases, call that menu Plugins.

openclaw config set adds a server from the terminal while the Gateway runs. It takes the server's settings, its entry, in JSON, a format of quoted names and values:

openclaw config set mcp.servers.docs \
  '{"url":"https://mcp.example.com/mcp","transport":"streamable-http"}' \
  --strict-json

It answered "Change will apply without restarting the gateway", and the Gateway applied it in about a tenth of a second. A server with a key takes one line in your key file, then an entry that uses your key's name:

echo 'DOCS_KEY=paste-your-key-here' >> ~/.openclaw/.env
openclaw config set mcp.servers.docs \
  '{"url":"https://mcp.example.com/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer ${DOCS_KEY}"}}' \
  --strict-json

That new key needed no restart in the test: the server received the real value in the next conversation. Changing that key's value later does need one, and openclaw gateway restart stops your agent for a moment.

A local server with a key takes this entry instead: {"command":"github-mcp-server","args":["stdio"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"${GITHUB_TOKEN}"}}. Write transport as above: Claude's apps write "type":"http", and a server saved with that fails, because config set doesn't translate it.

Your config file also accepts a direct edit. A new entry under mcp.servers in ~/.openclaw/openclaw.json, saved by hand, was live within three seconds. A mistake in that file can stop the Gateway from starting, so prefer the form or openclaw config set.

Your agent can make the change for you. Asked to add a server, it may reach for openclaw mcp add, which the running Gateway refuses, as it does in your terminal. openclaw config set worked in the test through exec, the tool your agent uses to run commands on your machine. So name that command in your request:

Add this MCP server to OpenClaw with `openclaw config set mcp.servers.<name>`,
not `openclaw mcp add`, because the Gateway is running.
My key is in ~/.openclaw/.env under the name <NAME>: write it as ${<NAME>}.
Then run `openclaw mcp doctor <name>` and show me what it says.
Server: <paste the address of the server's page>

The stand-in only followed its script, so a real model may go about it differently.

Keep your key out of that chat. ByteGrad, a web-development YouTube channel, warns that a key typed in chat goes to the AI model and "may be persisted in these session transcripts", the saved history of your conversations.

Then check what those roads didn't test. openclaw mcp doctor <name> runs with the Gateway on, and it caught the misspelled command the form had saved: "stdio command not found or not executable". It doesn't connect to the server, so it said ok for a server given a wrong key. For that, send your agent a new message and run the tools.effective command. A failing server shows there as a warning, such as authentication refused (401).

Check that it works, from your agent's side too

An entry saved through the form or openclaw config set only proves its settings are correctly written. openclaw mcp add also proves OpenClaw reached the server. Neither proves your agent got the tools, and four checks answer four different questions.

Only probe reaches the server, and none of the first three looks at what your agent received. A long thread on OpenClaw's public bug list (issue #114154, July to October 2026) reported servers that passed those checks while conversations never received their tools. OpenClaw's maintainers closed it on 24 October, because they could no longer confirm it on the version in development. It may or may not be gone from yours.

That is why tools.effective matters, with the --params part shown in the steps: it reads one conversation's list of tools. It showed a group headed "MCP server tools" after one message, and it leaves out any tool your rules remove. According to OpenClaw's docs, an agent's Tools panel in the Control UI shows the same list.

Rerun these checks after each update, because OpenClaw's commands change quickly: adding a server changed in one release. Updates broke my own OpenClaw setup again and again, and I spent a lot of time repairing it.

Here is every openclaw mcp command, and whether it runs while the Gateway is on:

Test on 4 November 2026, OpenClaw 2026.10.10; login and logout from OpenClaw's reference, read the same day.

Common MCP + OpenClaw errors and their fixes

When a check fails, the message usually points at the cause, and sometimes at the wrong one. If yours isn't here, paste the whole message into your agent or Claude Code, Anthropic's coding agent, and ask what to change.

After you fix a server, it can stay missing for a while. New conversations leave a failed server out for 30 seconds, then for twice as long after each new failure, up to 10 minutes. A success or a config change clears that wait.

Why the mcpServers block from other guides fails

Some guides still tell you to paste a list of servers into OpenClaw's config file. OpenClaw VPS, a hosting company, says on its setup page, read on 4 November 2026: "Drop a server entry under mcpServers, restart the gateway, done." The block looks like this:

{
  "mcpServers": {
    "filesystem": { "command": "node", "args": ["…"], "transport": "stdio" }
  }
}

That format belongs to Claude Code and Claude Desktop, Anthropic's desktop app, whose config files start with a mcpServers list. In March 2026, an OpenClaw user called Kaspre asked for the same list, to replace the small programs of 100 to 200 lines people wrote to link each server. OpenClaw's built-in support arrived under another name, mcp.servers, and its config file refuses any name it doesn't know. Pasted in on 2026.10.10, the block gave this:

OpenClaw config is invalid
Problem:
  - <root>: Unrecognized key: "mcpServers"

From then on, openclaw mcp list refused to run. The Gateway already running kept its old settings and logged "config reload skipped (invalid config)". A new start of the Gateway stopped on the same error, so the restart those guides ask for leaves you with no agent at all. OpenClaw VPS's page also shows that list inside one agent's settings, which was rejected too. Its troubleshooting command, openclaw logs --mcp, doesn't exist.

To recover, delete the block by hand, since the error names it. Otherwise, stop the Gateway and run OpenClaw's repair command:

openclaw gateway stop
openclaw doctor --fix
openclaw gateway start

With the Gateway still running, the repair refused to start ("Doctor could not enter maintenance"), because it needs the Gateway off. With the Gateway stopped, the repair restored the last settings that had worked. It kept the broken file beside it, under a name starting with openclaw.json.clobbered. Check afterwards that your other recent changes are still there.

The format OpenClaw accepts in that file looks like this, with your own home folder in place of /home/you. It doesn't need quotes around names:

{
  mcp: {
    servers: {
      memory: {
        command: "mcp-server-memory",
        env: { MEMORY_FILE_PATH: "/home/you/agent-memory.jsonl" },
      },
      docs: {
        url: "https://mcp.example.com/mcp",
        transport: "streamable-http",
      },
    },
  },
}

A list copied from a server's page or from Claude Desktop doesn't need retyping. Save it as .mcp.json in an empty folder and stop the Gateway, since the importer is refused while the Gateway runs. Then run OpenClaw's importer, first to preview what it would add, then to apply it:

openclaw migrate claude --from ./that-folder --dry-run
openclaw migrate apply claude --from ./that-folder --yes

The test's file listed a local and a remote server. The importer backed up OpenClaw's data and added both. It kept Claude's "type": "http" for the remote one, and that server then failed with the error 400. Running openclaw mcp set <name> '{"url":"<its address>","type":"http"}' turned it into "transport": "streamable-http", and openclaw mcp doctor <name> --probe passed.

Without --from, the importer reads your own Claude Code and Claude Desktop settings, according to its docs. That includes your instructions and skills, the written procedures Claude can load. So read the preview first.

Choose which tools your agent gets

Your server works, and your agent can now call everything it offers, including tools that write or delete. Three settings narrow that down, and the first two work on tool names, so the names come first.

Each tool reaches your agent as <server>__<tool>: the server's name, two underscores, then the tool's name. The server's part is called the prefix. OpenClaw cleans the prefix so that every AI provider accepts it. Characters other than letters, digits, _ and - become -. A name that doesn't start with a letter gets mcp- in front. A prefix over 30 characters is cut there.

A deny rule, a setting that takes a tool away from your agent, has to use that prefix:

Test on 4 November 2026, OpenClaw 2026.10.10.

Written with the name you gave the server, "Outlook Graph__*" or "2fa__*", the same rule matched nothing and the tools stayed. Short lowercase names avoid the problem.

Before filtering, find out which tools write or delete. Servers can label each tool as read-only or as destructive, meaning it can delete or overwrite. OpenClaw 2026.10.10 doesn't show those labels: openclaw mcp probe --json gave only names in the test. For a remote server, the names and the server's page are what you have to go on.

For a local server, ask your agent or Claude Code, which reads the labels for you. The stand-in couldn't test that request, since it only follows a script:

List the tools of this MCP server: <paste its start command>.
Read their labels (readOnlyHint, destructiveHint) if they have any,
and tell me which ones write or delete.

To do it yourself, these lines ask the server for its tool list and print each tool's labels. The only part to change is the start command, here mcp-server-memory:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| mcp-server-memory 2>/dev/null | tail -n 1 \
| node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{for(const t of JSON.parse(s).result.tools){const a=t.annotations||{};console.log(t.name,"readOnly:",a.readOnlyHint,"destructive:",a.destructiveHint)}})'

On the memory server, the labels marked the three delete_* tools as destructive. On the MCP project's filesystem server, which reads and writes files in one folder, they marked write_file, edit_file and move_file as destructive. A missing label prints undefined. The labels are the server's own claims, so use them to choose what to filter, never as a guarantee.

The first setting is the server's own filter. It decides which of a server's tools reach your agent at all. It uses the tool names without the prefix, and * stands for anything. These commands need the Gateway stopped. They add the filesystem server under the name files, limit it to one folder and to tools that only read, then take the delete tools away from the memory server:

npm install -g @modelcontextprotocol/server-filesystem
mkdir -p "$HOME/agent-files"
openclaw mcp add files --command mcp-server-filesystem --arg "$HOME/agent-files"
openclaw mcp tools files --include 'read_*,list_directory,search_files'
openclaw mcp tools memory --exclude 'delete_*'

With the Gateway running, this did the same for files: openclaw config set mcp.servers.files.toolFilter '{"include":["read_*","list_directory","search_files"]}' --strict-json. A pattern catches more than you may expect: on the filesystem server, read_* also took read_media_file and read_multiple_files. openclaw mcp tools <name> --clear removes the filter.

The second setting is a deny rule, tools.deny. It takes the prefixed names, and it beats any rule that allows the same tool. It can apply to every agent or to one, since OpenClaw can run several agents. Here research is one agent's name:

openclaw config set tools.deny '["memory__delete_*"]' --strict-json
openclaw config set agents.entries.research.tools.deny '["files__*"]' --strict-json

config set replaces the whole list, so repeat any entries already there. Both rules took effect without a restart. A model that asked for a denied tool by name anyway got Tool memory__delete_entities not found in the test, and nothing was deleted.

A rule that covers a whole server goes further, because OpenClaw then doesn't start that server. "files__*" removes one server. "bundle-mcp", OpenClaw's internal name for all your servers together, removes them all. With that rule in place, a new conversation started no server program in the test, against two without it.

The third setting is the tool profile. It is a preset list of tools that the other two settings then adjust. OpenClaw's first setup writes tools.profile: "full", which takes nothing away. In the test, coding kept the two servers' 25 tools and minimal hid them, and OpenClaw's docs say messaging keeps them. Leave it unless you chose a profile for another reason.

An agent that runs in a sandbox, an isolated container OpenClaw starts for its commands, has one more step (Hermes vs OpenClaw covers the trade-offs of that setup). MCP tools stay hidden from it until you add bundle-mcp to the setting tools.sandbox.tools.alsoAllow. openclaw doctor warns about it, and that is OpenClaw's general check, different from openclaw mcp doctor.

Approvals: who stops a write before it runs

An approval is a prompt that holds a tool call until a person says yes. The official text of the MCP standard asks applications for one: there "SHOULD always be a human in the loop with the ability to deny tool invocations". OpenClaw has a setting that sounds like it, openclaw mcp configure <server> --approval prompt, and it reaches less far than its name suggests.

OpenClaw's docs tie that setting to Codex, OpenAI's coding agent, one of the engines OpenClaw can use. An engine is the part that runs each of your agent's turns. OpenClaw uses its own unless you chose another, and the Runtime column of openclaw sessions list tells you: "OpenClaw Default" means its own.

With the memory server set to prompt, OpenClaw's own engine ran the model's call to memory__delete_entities at once. No question was asked, and the stored fact was gone.

OpenClaw also lets you set how much one conversation may do, its permission mode, and that didn't stop the write either. A conversation switched to read-only, a mode that limits file access and refuses commands, lost OpenClaw's own tools that write, going from 82 tools to 79. It kept all 25 MCP tools, including those that write or delete, and one that writes still ran. OpenClaw's page on those modes says their rules "describe OpenClaw-managed tools".

On OpenClaw's own engine, what stops a tool is a filter or a deny rule, never the approval setting. Four protections take tools or rights away before anything runs:

• Filter or deny the tools that write or delete. Do it for any server you don't fully trust.
• Give the server a key that can only read. Many services offer one. I once had to give OpenClaw an MCP server with very limited rights, precisely to keep OpenClaw from holding rights that were too high.
• Use the server's own read-only mode. Some servers have one, and the server's page says how to switch it on.
• Put a narrow server in front of your apps. Abhay Kulkarni, who makes OpenClaw tutorials, builds his servers as workflows in n8n, an automation tool. Each one exposes only the actions he picks, such as reading a Gmail account, and n8n logs every call.

Chris Fisher, a host of Linux Unplugged, a podcast on Linux and running your own servers, says MCP gives you "a place to kind of have control over what the agent can do". His co-host Wes Payne says the risk depends on what you connect: "what keys does it have for what things, what MCP tools do you connect in?". To decide which actions need a person's OK, see connecting an agent to your apps.

If your engine is Codex, the setting does work, according to OpenClaw's docs. Codex wasn't part of the test, so this comes from those docs. The setting has three modes:

• approve never asks. It suits servers you trust.
• prompt asks on every call. It keeps asking even after you answer "Allow Always".
• auto decides from the tool's labels. The MCP standard tells applications to treat those labels as untrusted unless the server is.

With no mode set, a server follows the conversation's permission mode. A conversation has full access by default, and full access never asks. "Allow Always" on a Codex prompt saves your OK for that agent, server and tool, whatever the tool is asked to do, and it counts only under auto or with no mode set. openclaw approvals get --gateway reads the document where those OKs are kept.

Keep server processes in check

A local server is a running program, and OpenClaw keeps one copy per conversation. Those copies stay alive between messages until the conversation is reset or deleted, that server's settings change, or the Gateway stops.

To see what that adds up to, the test opened ten short conversations with two servers connected. They left 20 running programs, using about 1.55 GB of memory, or about 78 MB per copy. Changing one setting of a server stopped every old copy of that server at once.

The copies add up on a Gateway that runs for days. Three users described it on OpenClaw's public bug list in October 2026 (issue #166017). JoernHoppe saw about 750 such programs in a few days. Juanpablo321 found 200 copies of two servers and a Gateway using 12.5 GB of memory after 71 hours.

Namchamvinhcuu, with Claude Code as the engine, had 121 copies after 4.5 days on a machine with 8 GB of memory. That Gateway then froze for 40 to 80 seconds at a time, scheduled jobs timed out and messages sent in by other services were lost.

The fix is one setting. mcp.sessionIdleTtlMs stops a conversation's servers after that many milliseconds without use, so 600000 means ten minutes. Left unset, OpenClaw keeps them on purpose, so that background work keeps its tools.

openclaw config set mcp.sessionIdleTtlMs 600000

Your server comes back by itself: in the test, the next message in that conversation started it again, and its tool worked. Set to 30,000, or thirty seconds, every idle copy was gone within 60 seconds. JoernHoppe set ten minutes, restarted once, and 47 hours later a listing showed none of the extra programs. Juanpablo321 set it without a restart, and that freed everything.

A report opened on 4 November 2026 says copies still pile up on 2026.10.9, on a Gateway run in Kubernetes, a system that hosts containers (issue #192498). So after setting it, look at Activity Monitor on a Mac, or ask your agent how many copies of your servers are running.

Two limits of 256 matter on a busy Gateway. OpenClaw's docs say a Gateway holds at most 256 sets of connections to servers. Past that, it stops the set idle the longest, and that conversation reconnects at its next message.

JoernHoppe adds that servers and ordinary commands share 256 places in the program that launches them. When servers fill those places, your agent's commands and file reads fail too. How much memory this leaves on a small, always-on machine is what the Mac mini for OpenClaw works through.

What a server costs your agent

Every tool your agent can call comes with a description and a list of parameters, its schema, which the AI model has to read. That text is part of the model's context, everything it reads on each turn, and it is billed in tokens, the short chunks of text models read and charge for.

This was the main complaint about MCP from OpenClaw's own creator. Peter Steinberger explained on The Pragmatic Engineer, a software-engineering podcast, in January 2026 that MCP makes an agent load every tool's functions and explanations when a session starts. He added that it gives the model no way to sort the results or feed one tool's result into another.

He put it shorter in February, on Lex Fridman's podcast: "Screw MCPs. Every MCP would be better as a CLI", meaning a command-line program. OpenClaw then had no built-in MCP support of its own. That support arrived in March 2026, in two releases.

Tool Search then removed most of the cost. Turned on by default in release 2026.9.6, on 23 September 2026, this feature hands the model tool details only when it asks. The model now gets three small tools instead of every schema: tool_search, tool_describe and dispatch_action. It also gets a short directory of OpenClaw's own tools and, for MCP, only a count of what was left out.

Test on 4 November 2026: OpenClaw 2026.10.10, @modelcontextprotocol/server-memory 2.0.1 and server-filesystem 2.1.0, a stand-in model that logged each request. Tokens counted with OpenAI's o200k tokenizer; other models count somewhat differently. Each server's figure was measured on its own, which is why 1,421 and 2,086 add up to one token more than the two measured together.

The system prompt, the standing instructions sent with every request, is the one row that grows with Tool Search on, because it carries that short directory. Even so, a request with both servers was a little over a third of the size it reached with Tool Search off.

OpenClaw VPS's page estimates about 200 tokens for a memory server and 800 or more for GitHub. That describes no current setup: the default cost is close to nothing, and the memory server alone came to 1,421 with Tool Search off.

The saving costs an extra step. A first call through Tool Search took three model requests in the test (search, call, answer), against two with Tool Search off. OpenClaw's release notes warn that "extra discovery turns can cost more, particularly with a small tool catalog". openclaw config set tools.toolSearch false turns it off, which can pay off with only a few tools and a model that handles them well.

Giving tool details only on request also tends to help the model pick the right tool, on the evidence from other systems. Anthropic reported in November 2025 that its own tool-search feature raised the accuracy of Claude Opus 4 from 49% to 74% on its internal MCP tests.

A May 2025 study by Gan and Sun, called RAG-MCP, gave a model called Qwen-max web-search tasks. It chose the right server 43% of the time when shown only relevant descriptions, against 14% with all of them.

That doesn't fix tools that look alike. Justin Spahr-Summers, one of MCP's two creators at Anthropic, said in April 2025 that how much tools overlap matters to how many you can add. His example was a server for GitLab and one for GitHub, two code-hosting services, side by side: they "look very similar to the model and confusion becomes easier".

OpenClaw already ships memory search, web fetching, a browser and file tools. In the test, the memory server's tools sat next to OpenClaw's own memory_search and memory_get, which is fine for a first try.

So add servers for what OpenClaw can't already do. OpenClaw has a browser, so a browser server is the clearest one to skip. Steinberger said in August 2026 that Chrome's own MCP server was "really annoying because it's this extra alert", which needs someone at the screen, so OpenClaw's project went back to its own browser extension. Which servers are worth it for everyday apps is the subject of connecting an AI agent to your apps.

Check also what your server has to send back. Text passes easily between a server and the model. In my own MCP use, images and documents stay harder: as soon as a file has to be downloaded along the way, it takes more work, though the standard keeps improving.

mcporter, the other road to MCP

mcporter is a command-line program that calls MCP servers without any help from the agent, and some guides teach it as the way in. InfraNodus, a text-analysis service, says in its install guide that OpenClaw "relies on MCPorter to access MCP servers", and Dench's guide starts from it too. That stopped being true in March 2026, when built-in support arrived. mcporter is still a real option, but your tool rules don't apply to it.

Steinberger started it, and the OpenClaw organisation on GitHub now maintains it (version 0.16.1, 27 October 2026). You use it as in mcporter list or mcporter call memory.read_graph. OpenClaw bundles a skill for it, a written procedure your agent can load, which teaches your agent to run those commands. That skill only works once the program itself is installed (npm install -g mcporter).

Three differences follow from that design:

• It keeps its own list. mcporter uses config/mcporter.json or ~/.mcporter/mcporter.json. In the test, adding a server with it left OpenClaw's file untouched, whatever some guides say, and openclaw mcp list didn't show that server.
• It adds nothing to each request. Your agent sees the skill, then runs commands. That was its point when OpenClaw had no built-in MCP. The model also has to think of using it: ByteGrad said in February 2026 that you still have to "coax it a little bit".
• Your deny rules don't reach it. Its calls are ordinary commands run through exec, not MCP tools. With every memory__* tool denied in the test, the model ran mcporter call memory.delete_entities …, and the entry was deleted.

To limit those calls, use tools.exec.mode, which governs every command your agent runs, not only mcporter's. It has two useful settings:

• allowlist runs only the commands on your list. In the test, ls was refused along with mcporter: exec denied: allowlist miss. The entry has to be the program's real file, which readlink -f finds. which mcporter alone left it refused.
• ask holds each command for your OK. You answer in the Control UI or a linked chat app. With nobody there to answer in the test, the command was refused.

openclaw config set tools.exec.mode '"allowlist"' --strict-json
openclaw approvals allowlist add --gateway "$(readlink -f "$(which mcporter)")"

Whether a tool comes as MCP or as a command matters less than how it's built, on the one controlled comparison available. Mario Zechner, who wrote pi, the agent OpenClaw's engine is built on, ran an MCP version and a command-line version of the same tool 120 times in August 2025. Both succeeded every time, and the MCP one was 23% faster and 2.5% cheaper.

Use openclaw mcp servers when you want your agent to see the tools and your rules to govern them. Use mcporter for a server your agent calls rarely, with tools.exec.mode as the limit.

Use OpenClaw as an MCP server for Claude Code or another client

Everything so far connects other programs to OpenClaw. Some readers want the opposite: OpenClaw itself as a server for another app, called an MCP client, such as Claude Code, Claude Desktop or Cursor, a code editor with AI. Two built-in commands do it, and they expose very different things.

Tool counts listed over MCP from each endpoint on 4 November 2026, OpenClaw 2026.10.10.

openclaw attach lets Claude Code use your agent's tools. It opens Claude Code on one OpenClaw conversation, the main one unless --session names another. Your other Claude Code servers stay out of that session. The servers you saved in mcp.servers weren't among the 34 tools.

openclaw mcp serve turns OpenClaw's chats into MCP tools. The app can list recent conversations from Telegram, Slack or any linked chat app, read them, wait for new messages and answer on the same channel. Claude Code adds it with claude mcp add openclaw -- openclaw mcp serve. If the Gateway is on another machine, the command also takes --url and --token-file, the file holding the Gateway's access key.

Claude.ai needs a bridge, because it connects from Anthropic's servers and needs a secure address on the internet (HTTPS), which a program on your machine is not. The most active bridge, freema/openclaw-mcp (188 stars on GitHub, updated 25 October 2026), runs as a web server you host, with an OAuth sign-in in front of it.

Another bridge, Helms-AI/openclaw-mcp-server, was written in a single day in February 2026 and hasn't changed since. A bridge holds your Gateway's key, so treat the machine it runs on like the Gateway itself.

If Claude Code or Codex runs your agent's turns

OpenClaw can run a conversation in its own engine or hand it to Claude Code or Codex. Neither was run here, because both need a real Anthropic or OpenAI account, so what follows comes from OpenClaw's docs, its code and its public bug list. The servers you save are shared, but each engine receives them its own way.

• Claude Code may still load every tool's schema. That would cost more tokens per request. OpenClaw's docs say Claude Code loads tools on demand, and issue #139477 was closed on 1 November 2026 because the problem no longer showed on the version in development. The code of 2026.10.10 still marks those tools as always loaded.
• Claude Code's helper agents may not get the servers you added. A helper agent is a conversation your agent starts with sessions_spawn. Issue #149406 is still open, and a user still saw the problem on 2026.10.6.
• Claude Code's idle copies should now stop. Users reported the idle setting doing nothing up to 2026.10.9. The code of 2026.10.10 carries the fix, which wasn't run here.
• Codex follows its own rules. According to the docs, the approval modes and "Allow Always" apply there, and a codex.agents list in a server's entry limits which agents receive it.

OpenClaw's docs can run ahead of its releases, so a menu or a setting may differ on yours. OpenClaw alternatives compares the other agents by the reason people leave, if these issues push you to look around.

Security: what a connected server can do

A connected server is code that can do whatever your agent can reach. Three facts help size the risk.

A local server runs with the Gateway's rights. It runs on the Gateway's machine, under the same user account, with the settings you give it. A second machine paired with the Gateway, which OpenClaw calls a node, can run a server itself, which keeps the server next to the files it works on. Servers that sign in through OpenClaw's OAuth don't work there.

A tool's description is text the model reads and you may never see. Invariant Labs, a security firm, showed in April 2025 that instructions hidden there can make an agent leak data or override what other servers told it. It called this tool poisoning. OpenClaw's Tool Search keeps MCP names and descriptions out of the system prompt, and it hands search results to the model marked as untrusted. With Tool Search off, they sit in every request.

OpenClaw has published 17 security advisories involving MCP. Advisories are public notices of a flaw. These came out between February and September 2026: 8 rated high, 8 medium and 1 low. The list held no newer one on 4 November. In one, bundled MCP tools could ignore your deny rules (fixed in 2026.4.20). In another, a redirect could send a server's custom headers, which can hold your key, to another site (fixed in 2026.5.12).

All 17 are fixed from 2026.8.1, released on 31 August 2026, and some were published after their fix. So run that version or a later one.

What stays at home when you run an agent yourself, and what still leaves, is covered in self-hosted AI agents.

Your action plan

Every action in this guide, in order, to tick as you go.