Walter MCP in Claude Code: A Practical Setup Guide

---

title: "Walter MCP in Claude Code: A Practical Setup GuideMost Walter MCP guides cover Claude on the web: Settings, Connectors, paste a URL. Claude Code is a different setup and a meaningfully different tool. It runs in your terminal, reads and writes files in your repo, and connects to MCP servers through a CLI rather than a settings page.

That last difference changes what the integration is useful for. In the web app you paste text in and get text back. In Claude Code the agent can walk a directory of markdown files, humanize a docs folder, or run a QC pass on every post in a content repo before you open a PR. This guide covers the setup and then the workflows that are actually worth it.

Table of Contents

1. What you're setting up
2. Add the server
3. Choose your scope
4. Authenticate
5. Verify the connection
6. Install Walter Skills
7. Workflows that only work in Claude Code
8. Troubleshooting
9. FAQs

1. What you're setting up

Two separate pieces, and you need both.

Walter MCP is the remote server that gives Claude the actual tools. It exposes three: walter_humanize for rewriting, walter_detect for AI detection, and walter_batch_humanize for processing several texts in one run. These are tool calls out to Walter, not things Claude can do on its own.

Walter Skills are markdown instruction files that tell Claude how to run a workflow: which detection threshold counts as a flag, which humanization mode to use, what the output should look like. Twelve of them, free and MIT licensed, in the walter-skills repo.

Without the server, a loaded skill gets followed perfectly and still can't perform the humanization or detection steps. Without the skills, the server works but you're re-describing your process in every session. Section 2 through 5 set up the server, section 6 adds the skills.

2. Add the server

One command, straight from Walter's official Claude Code docs:

claude mcp add walter-writes https://mcp-server.walterwrites.ai/mcp -t http

-t http is the short form of --transport http, and it's the part that matters. It tells Claude Code this is a remote server to connect to rather than a local command to launch. Leave it off and Claude Code treats the URL as something to execute, which fails. HTTP is the recommended transport for remote servers, and Walter's server runs over streamable HTTP.

Use the name walter-writes rather than inventing your own. It's what Walter's documentation uses throughout, so anything you look up later will match what you see in your terminal.

After the command runs, the server is registered but not yet authenticated. That happens in section 4.

3. Choose your scope

The command above adds Walter at local scope, which is the default and the one that surprises people most. Local scope means the server exists only for you, only in the project directory where you ran the command. Open a different repo and Walter isn't there.

Three options:

Local (default). Only you, only this project. Fine for trying it out.

User. Only you, but across every project on your machine. This is the right choice for most individual writers and developers, since you'll want Walter available wherever you're working:

claude mcp add walter-writes https://mcp-server.walterwrites.ai/mcp -t http --scope user

Project. Written to a .mcp.json file in the repo root, which you commit so everyone on the team inherits the server. This is the one to use for a shared content or docs repo:

claude mcp add walter-writes https://mcp-server.walterwrites.ai/mcp -t http --scope project

Project scope shares the server definition, not anyone's credentials. Each teammate still authenticates with their own Walter account, and Walter links each authorization to that person's own workspace, so tool calls run within their own plan's limits. That's also exactly what you want given Walter's terms prohibit account sharing.

If the same server name exists at more than one scope, local takes precedence over project, and project takes precedence over user. Worth knowing when a teammate reports behavior you can't reproduce.

One more note on project scope: Claude Code asks for approval before using servers from a checked-in .mcp.json, and its own documentation is explicit that you should verify you trust a server before connecting it. That's a sensible default rather than a bug.

4. Authenticate

Walter uses OAuth, so there's no API key to paste into the command.

Launch Claude Code and run:

/mcp

Then follow Walter's documented flow:

1. Select walter-writes from the server list and choose Authenticate.
2. Sign in to your Walter account in the browser window that opens, or create one.
3. Approve access on the authorization consent screen.
4. Return to Claude Code and confirm the server shows as connected and authenticated.

You only authorize once. After that the connection is linked to your Walter workspace, and you can revoke access at any time from your Walter account.

No config files to edit, no key in an environment variable, and nothing sensitive in your shell history.

5. Verify the connection

Check the configuration from your terminal:

claude mcp list
claude mcp get walter-writes

Inside a session, /mcp shows connection status, and you should see Walter's three tools listed.

The real test is a functional one. Ask Claude:

Humanize this sentence with Walter and show the detection score before and after: "In today's rapidly evolving digital landscape, organizations must strategically leverage innovative technologies to optimize operational efficiency."

If both tools are working, you'll get the rewrite back with a preservation report, plus a detection score from 0 to 100 and a verdict of likely human, unclear, or likely AI. Ask Claude to explain the results and walter_detect also returns the high-risk spans with notes on why they were flagged.

If you get a rewrite with no scores, Claude is paraphrasing on its own and the Walter tools aren't being called, which means the server isn't connected or authenticated yet.

6. Install Walter Skills

Claude Code is one of the agents the skills registry supports directly, so installation is a single command:

npx skills add walterwritesai/walter-skills

That installs all twelve. To install just one:

npx skills add walterwritesai/walter-skills --skill walter-docs-writer

For Claude Code specifically, three are worth knowing first.

SK-12, Docs Writer. Built for help center articles and product documentation, with code blocks, commands, and technical terms passing through unchanged. This is the one to reach for in a repo, because a general humanizer that paraphrases a command breaks it.

SK-02, Agency QC Pipeline. Runs a full detect, humanize, flag, and report pass. Useful before a PR that touches content.

SK-09, Content Refresh. Updates older posts without discarding what's already ranking, which pairs naturally with Claude Code's ability to walk a folder of existing files.

If you'd rather browse before installing, waltermcp.com is a community-maintained guide with walkthroughs and one-click skill copying. It's community-run rather than official, so treat the GitHub repo as the source of truth for anything that needs to be current.

7. Workflows that only work in Claude Code

This is the part that justifies the terminal setup over the web connector. Because Claude Code operates on your actual files, a few workflows become single prompts.

Humanize a folder, not a paste. In a static site or blog repo:

Go through every markdown file in content/posts/ from the last month. Run Walter detection on each, humanize only the ones scoring above 40, keep each post's target keyword exactly as written, and don't touch front matter or code blocks.

The agent reads the files, sends them through Walter, and writes the changes back. You review the diff like any other change.

When several files go through walter_batch_humanize together, each is processed individually. If one fails, for example by exceeding your word limit, the rest still succeed and you get partial results back rather than losing the whole run. How many items a batch can hold, and your daily word volume, depend on your Walter plan.

QC before you open a PR. With the QC skill loaded:

Run the QC pipeline on every markdown file changed on this branch and give me a summary I can paste into the PR description.

This turns content review into a step in your normal git workflow rather than a separate process in a separate tool.

Fix documentation without breaking it. With Docs Writer loaded:

Rewrite the prose in docs/ so it reads naturally. Leave every code block, command, flag, and API path exactly as it is.

Protect terms across a whole repo. Keyword and brand preservation scale in a way manual editing doesn't:

Humanize the README and every file in guides/. The product name, CLI command names, and all version numbers must survive unchanged.

Keep it interactive. Walter's usage terms describe the MCP server as intended for interactive, user-to-assistant workflows, which is exactly what everything above is: you prompt, Claude acts, you review. If you want humanization running unattended, in CI or a scheduled job with nobody in the loop, that's what Walter's REST API is for, not the MCP server.

Scope what the agent touches. Worth saying plainly, since Claude Code can write to any file in scope: Walter rewrites prose. It does nothing useful to code logic, and you shouldn't point it at source files. Name the directories and file types explicitly in your prompt, and review the diff before committing. The approval step Claude Code shows for each tool call is there for a reason.

8. Troubleshooting

"MCP server walter-writes already exists in local config." You ran the add command twice at the same scope. Either it's already set up, or remove it first with claude mcp remove walter-writes and re-add.

Walter isn't showing up in a different project. It's at local scope. Re-add it with --scope user.

The URL gets treated as a command. You left off -t http. Remove and re-add with the flag.

Rewrites come back with no detection scores. The server isn't connected or isn't authenticated. Run /mcp, select walter-writes, and choose Authenticate if it's offered.

Skills installed but nothing different happens. Skills describe a workflow; they need the server to execute it. Check the connection first, since this is almost always a missing or unauthenticated server rather than a skills problem.

A teammate sees different behavior. Check for the same server name at multiple scopes, since local overrides project overrides user.

9. FAQs

How do I add Walter MCP to Claude Code?
Run claude mcp add walter-writes https://mcp-server.walterwrites.ai/mcp -t http, then launch Claude Code, run /mcp, select walter-writes, choose Authenticate, and sign in with your Walter account. Add --scope user to make it available across all your projects.

Do I need an API key?
No. Walter authenticates through OAuth. You sign in with your Walter account in the browser during the /mcp Authenticate step, so no key goes into the command or your environment. API keys are only needed if you use Walter's REST API directly.

Which scope should I use?
User scope for personal use across all your projects. Project scope for a shared team repo, which writes a .mcp.json you commit. The default local scope only works in the directory where you ran the command.

Can my team share one setup?
Yes, with project scope. The server definition is shared through the committed .mcp.json, while each person authenticates with their own Walter account.

How is this different from Walter in the Claude web app?
Same tools, different context. The web connector works on text you paste in. Claude Code works on files in your repo, so it can humanize a whole folder, run QC on a branch before a PR, or rewrite a docs directory while leaving code blocks intact.

Will it modify my code?
Only if you point it at code, which you shouldn't. Walter rewrites prose. Scope your prompts to specific directories and file types, and review the diff before committing.

Do I need Walter Skills too?
For repeatable workflows, yes. The server provides the tools and the skills define the process. Install with npx skills add walterwritesai/walter-skills.

Is waltermcp.com official?
No, it's a community-maintained guide. Useful as a secondary reference, but check the GitHub repo and Walter's own documentation for anything that needs to be current.

What tools does Walter add to Claude Code?
Three: walter_humanize for rewriting with keyword, entity, URL, and structure preservation; walter_detect for a 0 to 100 score, a verdict, and high-risk spans; and walter_batch_humanize for processing multiple texts in one run with partial results if any single item fails.

Can I run Walter MCP in CI or a scheduled job?
Walter describes the MCP server as intended for interactive, user-to-assistant workflows. For unattended automation, use Walter's REST API instead, documented at docs.walterwrites.ai.