Walter MCP in Gemini CLI: Setup and Workflows

One config entry, one OAuth sign-in, and the terminal workflows that make the connection worth setting up.

Gemini CLI can read and write the files in your project, which makes it a good home for writing tools, not just coding tools. Connect Walter Writes AI's MCP server and Gemini can run AI detection on a markdown file, humanize only the passages that need it, and write the result back to disk without you copying text between a terminal and a browser tab.

Before the setup, one thing has changed this year that affects who should follow which part of this guide. On June 18, 2026, Google stopped serving Gemini CLI requests for free-tier users and Google AI Pro and Ultra subscribers and moved those users to the new Antigravity CLI. Gemini CLI still works with paid Gemini API keys, Gemini Code Assist Standard and Enterprise licenses, and Google Cloud access. If you're in that group, sections 2 through 8 are for you. If you were moved to Antigravity CLI, jump to section 9. The Walter server and the workflows are the same either way. Only the config file changes.

Table of Contents

1. What you're connecting
2. Add the server (settings.json)
3. Or add it with one command
4. Authenticate with OAuth
5. Verify the connection
6. Scope, tool filtering, and confirmations
7. Add Walter Skills (optional)
8. Workflows worth using
9. Using Antigravity CLI instead
10. Troubleshooting
11. FAQs

1. What you're connecting

Walter's MCP server is a remote server at:

https://mcp-server.walterwrites.ai/mcp

It uses OAuth, so there's no API key to paste. You sign in to your Walter account once in a browser, and tool calls then run under your Walter workspace's plan and limits.

It exposes three tools:

• walter_humanize rewrites AI-generated text to read naturally, with adjustable rewrite strength. It preserves keywords, named entities, URLs, and document structure, and returns a preservation report with the rewritten text.
• walter_detect scores text from 0 to 100 for AI patterns and returns a verdict (likely human, unclear, or likely AI) plus the specific high-risk spans behind the score. Explanations can be turned on for detailed writing advice.
• walter_batch_humanize handles several texts in one call, with shared defaults and per-item overrides. If one item fails, the others still return, with per-item reports and a batch summary.

Inside Gemini CLI, MCP tools get a qualified name in the format mcp_{serverName}_{toolName}. With the server named walter-writes, you'll see names like mcp_walter-writes_walter_detect. You don't need to type these. Gemini picks the tool from your request, but it helps to recognize them in confirmation prompts and logs.

2. Add the server (settings.json)

This is the method in Walter's official Gemini CLI guide.

Open your user settings file:

nano ~/.gemini/settings.json

Add Walter under mcpServers:

{
  "mcpServers": {
    "walter-writes": {
      "url": "https://mcp-server.walterwrites.ai/mcp"
    }
  }
}

Two things to watch:

Merge, don't replace. If your settings.json already has content (theme, model, auth settings, other MCP servers), add the walter-writes entry inside the existing mcpServers object instead of overwriting the file. A full file might look like this:

{
  "general": {
    "defaultApprovalMode": "default"
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "walter-writes": {
      "url": "https://mcp-server.walterwrites.ai/mcp"
    }
  }
}

Don't add a transport key. Walter's docs call this out specifically: adding "transport" causes a validation error, because Gemini CLI infers the transport from the URL fields.

A note on url vs httpUrl

If you've read older Gemini CLI docs, you may have seen that url is for SSE and httpUrl is for Streamable HTTP. That's out of date. In current Gemini CLI source, httpUrl is marked deprecated, and a bare url tries Streamable HTTP first and falls back to SSE only if that fails. Walter's server is Streamable HTTP, so url works. If you want to be explicit, current versions accept an optional type field:

"walter-writes": {
  "url": "https://mcp-server.walterwrites.ai/mcp",
  "type": "http"
}

That's type, not transport. Either form works on a current build.

3. Or add it with one command

If you'd rather not edit JSON by hand, Gemini CLI has an mcp add command that writes the same entry for you:

gemini mcp add --scope user --transport http walter-writes https://mcp-server.walterwrites.ai/mcp

What the flags do:

• --scope user writes to ~/.gemini/settings.json, so Walter is available in every project. The default is project, which writes to .gemini/settings.json in the current directory.
• --transport http tells Gemini CLI this is a Streamable HTTP server. The default transport for mcp add is stdio, which is wrong for a remote URL, so don't skip this flag.

To check or undo it later:

gemini mcp list
gemini mcp remove --scope user walter-writes

Note that remove also defaults to project scope, so pass --scope user if that's where you added it.

4. Authenticate with OAuth

Start Gemini CLI:

gemini

If you don't have it installed globally, npx @google/gemini-cli works too.

Then, inside the session:

/mcp auth walter-writes

A browser window opens for Walter Writes AI. Sign in, approve access, and return to the terminal. Gemini CLI stores the token in ~/.gemini/mcp-oauth-tokens.json and reuses it in later sessions, so you only do this once per machine unless you revoke access.

Running /mcp auth without a server name lists every server that needs authentication, which is handy if you've just added several.

Working over SSH or in a container? The OAuth flow needs a local browser and a localhost callback, so it won't complete in a headless environment. Authenticate on a machine with a browser first, or run Gemini CLI locally for the initial sign-in.

5. Verify the connection

Inside the session:

/mcp

You should see walter-writes listed as connected, with its three tools. If it shows as disconnected or needing auth, run /mcp auth walter-writes again.

Then do a quick real call:

Use the walter-writes MCP server to run walter_detect on this text and show the score, verdict, and any high-risk spans:

"In today's fast-paced digital landscape, organizations must leverage innovative solutions to unlock new opportunities and drive meaningful growth."

Gemini will ask you to confirm the tool call (more on that next). Approve it, and you should get a score and verdict back. That sentence is about as formulaic as AI writing gets, so expect it to score high.

6. Scope, tool filtering, and confirmations

User vs project scope. User scope (~/.gemini/settings.json) makes Walter available everywhere. Project scope (.gemini/settings.json in a repo) keeps it to one project and lets you commit the config so teammates get the same setup. Each person still authenticates with their own Walter account, because tokens live in each user's home directory, not in the repo.

Limit which tools load. If a project only needs detection, an allowlist keeps Gemini from reaching for the other tools:

"walter-writes": {
  "url": "https://mcp-server.walterwrites.ai/mcp",
  "includeTools": ["walter_detect"]
}

excludeTools does the opposite and takes precedence if you set both.

Confirmations. By default, Gemini CLI asks before every MCP tool call. You'll see four options: allow once, always allow this tool, always allow this server, or cancel. For daily use, "always allow this tool" on walter_detect and walter_humanize is a reasonable middle ground.

There's also a "trust": true setting that skips all confirmations for a server. It's convenient for scripted runs (see workflow 5), but it applies to every tool on that server, so only use it in a config you control.

Enable or disable without deleting. gemini mcp disable walter-writes and gemini mcp enable walter-writes (or /mcp disable and /mcp enable inside a session) toggle the server without removing its config. Add --session to make the change apply only to the current session.

7. Add Walter Skills (optional)

The MCP server gives Gemini the tools. Walter Skills give it repeatable instructions for using them on specific kinds of content: SEO articles, agency QC, local SEO pages, content refreshes, docs, newsletters, and more. There are 12 in the free, open-source repo at github.com/walterwritesai/walter-skills.

Install all of them:

npx skills add walterwritesai/walter-skills

Or just one:

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

The skills installer supports Claude Code, Cursor, Windsurf, and 60+ other agents. If Gemini CLI isn't among the agents it offers to install for on your machine, you can still use any skill by copying its SKILL.md into your project's .gemini/skills/ folder, or by referencing it from your GEMINI.md.

8. Workflows worth using

These are the workflows where running Walter from a terminal agent beats pasting text into a web app.

Workflow 1: Detect first, humanize only what's flagged

Gemini CLI lets you reference files with @. Use that to point it at a draft:

Read @content/posts/launch-announcement.md.
Use the walter-writes MCP server to run walter_detect on it with explanations on.
Then run walter_humanize only on the high-risk spans it returns.
Keep all headings, code blocks, links, and front matter unchanged.
Write the result back to the same file and show me a short diff summary plus the before and after scores.

This keeps your own writing intact in the sections that were already fine, and it uses fewer words from your Walter plan than humanizing the whole file.

Workflow 2: Protect technical terms

Docs and dev content are full of terms that must not change: API names, flags, product names, version numbers. Walter preserves keywords and entities by default, but naming them removes any guesswork:

Humanize the "Overview" and "Why this matters" sections of @docs/getting-started.md with walter_humanize.
Do not change these terms: "Webhooks API", "--dry-run", "v3.2", "OAuth 2.0", or anything inside backticks.
Leave all other sections untouched.

Workflow 3: Batch a folder

For a directory of short pieces (product descriptions, release notes, social captions), batch them in one call instead of one at a time:

Read every .md file in @content/changelog/.
Send the body text of each to walter_batch_humanize in a single call.
Save each result to content/changelog/humanized/ with the same filename.
Then list each file with its walter_detect score before and after.

Because batch calls return per-item reports, one failed item doesn't sink the whole run. Gemini can tell you which file failed and retry just that one.

Workflow 4: Make it the default with GEMINI.md

Gemini CLI loads GEMINI.md files as standing instructions. Put your house rules there so you don't repeat them in every prompt:

## Writing workflow

- When asked to humanize content, always run walter_detect first and only humanize spans flagged as high risk.
- Never change text inside code blocks, inline code, URLs, or YAML front matter.
- Preserve product names, API names, and version numbers exactly.
- After humanizing, run walter_detect again and report before and after scores.

Put it at the project root for one repo, or in ~/.gemini/GEMINI.md to apply it everywhere.

Workflow 5: Headless runs for scripts

Gemini CLI's -p flag runs a single prompt non-interactively, which makes it scriptable:

gemini -p "Run walter_detect on @drafts/post.md and print only the score and verdict." \
  --allowed-mcp-server-names walter-writes

--allowed-mcp-server-names limits the run to the Walter server, so nothing else loads.

Two things make headless runs work:

1. Authenticate interactively first. Run gemini and /mcp auth walter-writes once on the machine. The stored token is reused by later headless runs.
2. Handle confirmations. There's no one to approve tool calls in a headless run. Rather than using --yolo (which auto-approves every tool, including shell commands), set "trust": true on just the walter-writes entry in a project-scoped .gemini/settings.json used for these scripts. That skips confirmations for Walter's tools only.

A practical use is a pre-publish check: run detection on every changed markdown file in a branch and print the scores, so you see which pages might draw a false positive before they go live.

9. Using Antigravity CLI instead

If you were on Gemini CLI's free tier or a Google AI Pro or Ultra subscription, you're now on Antigravity CLI, launched with agy. Walter's server works the same way there, but the config moved and one key changed.

The config file is different. Antigravity CLI doesn't read MCP servers from ~/.gemini/settings.json. It uses a standalone file:

• Global: ~/.gemini/config/mcp_config.json
• Workspace: .agents/mcp_config.json in your project root

The key is serverUrl. Antigravity doesn't support the legacy url or httpUrl keys for remote servers. Use:

{
  "mcpServers": {
    "walter-writes": {
      "serverUrl": "https://mcp-server.walterwrites.ai/mcp"
    }
  }
}

OAuth is handled for you. For servers that support dynamic client registration, Antigravity runs the OAuth flow automatically, so serverUrl is all you need. Sign in to Walter when prompted.

Managing it. Type /mcp in Antigravity CLI to open the MCP manager, where you can see server status, reload configs, and check connection logs. To turn a server off temporarily, set "disabled": true. To hide specific tools, use disabledTools.

Migrating an existing setup. Antigravity's agy plugin import gemini command converts Gemini CLI extensions, including their MCP server definitions. For a server you added directly to settings.json, like Walter, copy the entry into mcp_config.json and rename url to serverUrl. Your GEMINI.md files keep working unchanged. Workspace skills need to move from .gemini/skills/ to .agents/skills/.

Walter's documentation doesn't have an Antigravity-specific guide yet, so this section follows Antigravity's own MCP docs. Everything in section 8 carries over, since the tools and prompts are identical.

10. Troubleshooting

/mcp shows walter-writes as disconnected.
Run /mcp auth walter-writes. If it still fails, check the URL for typos and confirm it ends in /mcp.

Validation error after editing settings.json.
Usually a "transport" key or a JSON syntax issue such as a missing comma between server entries. Remove transport (use type if you need to be explicit) and validate the JSON.

gemini mcp add created a stdio server.
You left off --transport http. Remove the entry and add it again with the flag.

The browser window never opens during auth.
You're likely in a headless environment. Authenticate on a machine with a browser first.

Gemini answers without calling Walter.
Name the server and the tool in your prompt ("use the walter-writes MCP server to run walter_detect"). If you've set includeTools, confirm the tool you're asking for is in the list.

Headless runs hang or skip the tool.
There's no one to approve the call. Set "trust": true on the Walter entry in a project config used only for those scripts.

Calls stop working partway through a big batch.
You may have hit your Walter plan's daily word volume or batch size limit. Split the job or check your Walter account.

Gemini CLI says it can't serve requests for your account.
If you're on the free tier or a Google AI Pro or Ultra plan, that's the June 18, 2026 change. Set Walter up in Antigravity CLI using section 9.

11. FAQs

How do I add Walter MCP to Gemini CLI?
Add a walter-writes entry under mcpServers in ~/.gemini/settings.json with "url": "https://mcp-server.walterwrites.ai/mcp", or run gemini mcp add --scope user --transport http walter-writes https://mcp-server.walterwrites.ai/mcp. Then run /mcp auth walter-writes inside Gemini CLI to sign in.

Does Walter MCP need an API key in Gemini CLI?
No. Walter's MCP server uses OAuth. You sign in to your Walter account once in a browser, and Gemini CLI stores the token for later sessions.

Should I use url or httpUrl for Walter in Gemini CLI?
Use url, as Walter's docs show. In current Gemini CLI, httpUrl is deprecated, and url tries Streamable HTTP first with SSE as a fallback. You can add "type": "http" to be explicit, but don't add a transport key.

Can I still use Gemini CLI after June 18, 2026?
Yes, with paid Gemini API keys, Gemini Code Assist Standard or Enterprise licenses, or Google Cloud access. Free-tier users and Google AI Pro and Ultra subscribers were moved to Antigravity CLI.

How do I set up Walter MCP in Antigravity CLI?
Add Walter to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json for one project) under mcpServers, using "serverUrl": "https://mcp-server.walterwrites.ai/mcp". Antigravity handles OAuth automatically for servers that support dynamic client registration.

Can Gemini CLI humanize files directly?
Yes. Reference a file with @path/to/file.md, ask Gemini to run Walter's tools on it, and tell it to write the result back. Gemini CLI handles the file reading and writing, and Walter handles detection and humanization.

How do I stop Gemini CLI from asking to confirm every Walter call?
Choose "always allow this tool" or "always allow this server" at the confirmation prompt. For scripts, set "trust": true on the Walter server entry, which skips confirmations for that server only.

Does Walter MCP work with Walter Skills in Gemini CLI?
Yes. Install them with npx skills add walterwritesai/walter-skills. If the installer doesn't list Gemini CLI on your machine, copy a skill's SKILL.md into .gemini/skills/ or reference it from GEMINI.md.