Mohab Abdelkarim

Posted on Oct 23

Walter MCP vs Walter API: Which One Should You Use?

#mcp #ai #webdev #api

Walter Writes AI gives developers two ways to use its humanizer and AI detector. The MCP server plugs Walter into AI assistants like Claude, ChatGPT, and Claude Code, so the assistant can call Walter's tools in the middle of a conversation. The REST API gives your own code direct HTTP access to Walter's services, with API keys, async jobs, and webhooks.

They sound like two doors into the same room, but they're built for different jobs. They expose different capabilities, authenticate differently, and are limited differently. This post walks through both using Walter's official documentation, with code for the API and setup and prompts for MCP, so you can pick the right one for what you're building.

What Each One Is
Side by Side
When to Use Walter MCP
When to Use the Walter API
The Same Workflow, Both Ways
API Details That Matter in Production
Pricing and Limits
Using Both Together
Decision Guide
FAQs

1. What Each One Is

Walter MCP is a remote Model Context Protocol server at https://mcp-server.walterwrites.ai/mcp. Connect it to an MCP-compatible assistant and the assistant gets 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.
walter_detect returns a 0 to 100 score, a verdict (likely human, unclear, or likely AI), and high-risk spans, with optional explanations.
walter_batch_humanize processes several texts in one run with shared defaults and per-item overrides. If one item fails, the rest still return, with per-item reports and a batch summary.

You don't call these tools yourself. You ask the assistant in plain language, and it decides when and how to call them.

Walter API is a REST API at https://developer-portal.walterwrites.ai/api. Your code sends JSON over HTTPS with an API key. It covers more services than the MCP server:

POST /api/humanizer/
POST /api/detector/
POST /api/detect-and-humanize/
POST /api/plagiarism/scan/
POST /api/grammar/correct/
POST /api/voice-detector/detect/
POST /api/image-detector/predict/
GET /api/jobs/{task_id}/ for async results

2. Side by Side

Who calls it

MCP: an AI assistant, on your behalf, from natural-language instructions
API: your code, with explicit HTTP requests

Where it runs

MCP: Claude on the web, desktop, and mobile, Claude Code, ChatGPT, Gemini CLI, and Open WebUI
API: anywhere you can make an HTTPS request: backends, scripts, CI jobs, serverless functions

Authentication

MCP: OAuth. You sign in to your Walter account once and approve access. No key to store.
API: an X-API-Key header, with scopes chosen per key (Humanizer, AI Detector, Image Detector, or a combination)

Capabilities

MCP: humanize, detect, and batch humanize
API: humanize, detect, detect-and-humanize, plagiarism, grammar, voice detection, and image detection

Humanizer controls

MCP: documented keyword, entity, URL, and structure preservation, adjustable rewrite strength, and a preservation report
API: the humanizer reference documents content plus async options (poll, callback_url, webhook_secret)

Detection output

MCP: score from 0 to 100, verdict, high-risk spans
API: ai_score from 0.0 to 1.0, a binary result of ai or human, and per-sentence items with their own scores

Async and webhooks

MCP: not applicable; the assistant waits for each tool call
API: polling and webhooks on the humanizer, detector, and detect-and-humanize endpoints

Limits and billing

MCP: runs under your Walter workspace's plan, which sets limits such as daily word volume and batch size
API: a shared credit pool, generally 1 credit per word for text endpoints, plus rate limits and a pending-jobs cap

Best for

MCP: interactive editing, content workflows inside an assistant, and agentic file work in Claude Code
API: products, pipelines, automation, and anything that needs repeatable, programmatic control

3. When to Use Walter MCP

Choose MCP when a person, or an AI agent working for one, is in the loop.

You draft in an AI assistant. If your content already lives in Claude or ChatGPT, MCP removes the copy-paste loop. You ask the assistant to check and humanize, and the results come back into the same conversation.

You want instruction-level control without writing code. Because the assistant orchestrates the tools, you can describe a whole workflow in one prompt: detect first, humanize only the flagged spans, keep these exact keywords, then re-check.

You work with files in Claude Code. In Claude Code, the assistant can read drafts from your repo, run Walter on them, and write results back, which makes MCP surprisingly capable for batch content work without a custom script.

You want keyword preservation out of the box. Walter's MCP documentation explicitly describes walter_humanize as preserving keywords, entities, URLs, and structure, with a report showing what it kept.

Setup in Claude Code is one command:

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

Then run /mcp, select walter-writes, choose Authenticate, and sign in. For Claude on the web or desktop, ChatGPT, and the other supported clients, add a custom connector with the same URL and sign in when prompted. Walter's docs have a guide for each.

Add Walter Skills for repeatable workflows. Walter publishes 12 free, MIT-licensed skill files that tell the assistant how to run specific workflows, such as SEO writing, agency QC, local SEO, and programmatic SEO:

npx skills add walterwritesai/walter-skills

The repo is at github.com/walterwritesai/walter-skills. If you get stuck on setup, waltermcp.com is a community-run guide, not an official Walter resource, so treat Walter's own docs as the source of truth.

4. When to Use the Walter API

Choose the API when software is in the loop.

You're building a product. If Walter's humanizer or detector is a feature inside your app, such as a "check for AI" button or an automatic rewrite step, you need the API. MCP is for assistants, not end-user product features.

You need services beyond humanize and detect. Plagiarism scanning, grammar correction, voice detection, and image detection are API-only.

You need deterministic, testable behavior. An API call does exactly what your code says, with no assistant interpreting your instructions. That's what you want in CI, scheduled jobs, and production pipelines.

You need scale and async. The API supports async processing with polling and webhooks, so you can submit many jobs without holding connections open, subject to your plan's pending-jobs limit.

You need a server-side threshold. The detect-and-humanize endpoint scores text and only humanizes it if the AI score is above a detection_threshold you set, in a single request.

Getting a key: create one on the API Keys page of the Developer Portal at platform.walterwrites.ai/api-keys, choose its scopes, and copy it immediately, because it's shown only once. Walter's guidance is to keep keys out of client-side code, public repos, and logs, store them in environment variables or a secrets manager, use separate keys for development and production, and revoke keys you no longer need.

5. The Same Workflow, Both Ways

The workflow: check a draft, and only humanize it if it looks AI-generated.

With MCP

In Claude, Claude Code, or ChatGPT with Walter connected:

Use the walter-writes MCP server.
1. Run walter_detect on the draft below with explanations on.
2. If it's flagged, humanize only the high-risk spans with walter_humanize,
   preserving "Acme Sync Pro", "$49/month", and every URL.
3. Run walter_detect again and give me the final text, both scores,
   and the preservation report.

[draft]

No code, and the assistant handles sequencing. The trade-off is that the assistant interprets your instructions, so it's worth checking the tool calls it makes the first few times.

With the API

The detect-and-humanize endpoint does the conditional step on Walter's side:

import os
import requests

BASE = "https://developer-portal.walterwrites.ai/api"
HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": os.environ["WALTER_API_KEY"],  # key needs humanizer + ai_detector scopes
}

def check_and_fix(text: str, threshold: float = 0.5) -> dict:
    resp = requests.post(
        f"{BASE}/detect-and-humanize/",
        headers=HEADERS,
        json={"content": text, "detection_threshold": threshold},
        timeout=120,
    )
    resp.raise_for_status()
    data = resp.json()

    if data.get("humanized"):
        final = data["humanized_content"]
    else:
        final = data["content"]  # unchanged; per-sentence scores in data["detection_items"]

    return {
        "ai_score": data["ai_score"],
        "needs_humanization": data["needs_humanization"],
        "text": final,
    }

Fully deterministic, easy to test, and easy to drop into a backend. The trade-off is that you write and maintain the code, and the humanizer API reference documents only the content field and async options, so if you need specific phrases kept, plan to verify them in your own code after the call.

6. API Details That Matter in Production

Word limits. The humanizer accepts 50 to 2,000 words per request. Requests outside that range return 400 before any credits are charged.

Sync rate limits. By default, sync humanizer calls are limited to 3 requests per minute and sync detector calls to 10 per minute, alongside per-user and per-IP limits. Limits may vary by plan.

Use async for volume. Async requests aren't subject to the per-minute limit. They're constrained by credits and a pending-jobs cap that depends on your plan, ranging from 2 pending jobs on the trial to 50 on the largest plan. Add poll: true, a callback_url, or both:

import time

def humanize_async(text: str) -> str:
    resp = requests.post(
        f"{BASE}/humanizer/",
        headers=HEADERS,
        json={"content": text, "poll": True},
        timeout=30,
    )
    resp.raise_for_status()  # expect 202 Accepted
    task_id = resp.json()["task_id"]

    wait = 2  # Walter's recommended schedule: start at 2s, double, cap at 30s
    while True:
        time.sleep(wait)
        job = requests.get(f"{BASE}/jobs/{task_id}/", headers=HEADERS, timeout=30)
        job.raise_for_status()
        data = job.json()
        if data["status"] == "success":
            return data["result"]
        if data["status"] == "failed":
            raise RuntimeError(data.get("error"))  # credits are refunded on failure
        wait = min(wait * 2, 30)

Results expire after one hour, after which the jobs endpoint returns 404, so fetch them promptly.

Webhooks. With a callback_url, Walter POSTs the same JSON as the polling response when the job completes and retries failed deliveries up to 3 times with exponential backoff. The URL must be publicly routable. If you set a webhook_secret, verify it on arrival:

import hmac
import os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["WALTER_WEBHOOK_SECRET"]

@app.post("/walter-webhook")
def walter_webhook():
    received = request.headers.get("X-Webhook-Secret", "")
    if not hmac.compare_digest(received, SECRET):
        abort(401)
    payload = request.get_json()
    # payload["task_id"], payload["status"], payload["result"], ...
    return "", 204

Errors and retries. Use the code field rather than the error string for programmatic handling. Retry 429 and 5xx errors with exponential backoff, and respect the Retry-After header on rate limits. Don't retry 400, 401, or 403; fix the request, key, or account state first. Useful codes to handle explicitly include min_words_not_met, max_words_exceeded, insufficient_credits, credits_exhausted, and too_many_pending_jobs.

Reading detector scores. The detector returns ai_score from 0.0 to 1.0 and a binary result that's ai above 0.5. Walter's docs describe 0.0 to 0.3 as human with high confidence, 0.3 to 0.5 as likely human, 0.5 to 0.7 as likely AI, and 0.7 to 1.0 as AI-generated with high confidence. The per-sentence items array is what you want if you're highlighting flagged sentences in a UI.

7. Pricing and Limits

API credits. The API uses a single shared credit pool across Walter's services. Most text endpoints cost 1 credit per word of input, plagiarism scans cost a flat 2 credits, voice detection costs 10 credits per second of audio, and image detection is priced by resolution with a minimum of 6 credits. Failed requests are refunded automatically. Credits reset each billing cycle and don't roll over. Published monthly plans:

300K credits: $49
1M credits: $129
2M credits: $229
5M credits: $479
12M credits: $899
25M credits: $1,699

New accounts get a free trial of 2,000 credits, usable for 5 days, with no credit card required.

MCP limits. The MCP server runs under your Walter workspace's plan. Walter's documentation says availability and limits depend on the plan, including daily word volume and the number of items allowed per batch, and that workspace admins can control usage. Walter's docs don't state whether MCP usage and API credits share a pool, so check your own plan before you budget for both.

8. Using Both Together

Many teams end up with both, and they fit together naturally:

MCP for the editorial side. Writers and editors draft, check, and humanize inside Claude or ChatGPT, with Walter Skills enforcing a consistent process.
API for the system side. Your CMS or publishing pipeline calls the detector on every piece before it goes live, logs the per-sentence results, and routes anything above a threshold back for review.

A practical pattern: use MCP to develop and tune a workflow interactively, such as which threshold makes sense or which phrases should never change, then encode the settled version in code against the API once it needs to run unattended.

9. Decision Guide

Use Walter MCP if:

You or your team work inside Claude, ChatGPT, Claude Code, or another MCP client
You want to describe workflows in plain language instead of writing code
You want documented keyword and entity preservation with a preservation report
You don't want to manage API keys

Use the Walter API if:

Walter is a feature in a product you're building
You need plagiarism, grammar, voice, or image detection
You need async processing, webhooks, or a server-side detection threshold
You need deterministic behavior for CI, scheduled jobs, or production pipelines

Use both if:

People edit interactively and systems check automatically
You want to prototype a workflow in an assistant and then productionize it

10. FAQs

What's the difference between Walter MCP and the Walter API?
Walter MCP is a server that lets AI assistants like Claude, ChatGPT, and Claude Code call Walter's humanize, detect, and batch humanize tools from natural-language instructions. The Walter API is a REST API your own code calls directly with an API key, and it covers more services, including detect-and-humanize, plagiarism, grammar, voice detection, and image detection.

Do I need an API key to use Walter MCP?
No. Walter MCP uses OAuth. You sign in to your Walter account once and approve access, and tool calls run under your workspace's plan.

Does the Walter API support async requests?
Yes. The humanizer, detector, and detect-and-humanize endpoints accept poll: true, a callback_url, or both. They return 202 Accepted with a task_id, and you fetch results from GET /api/jobs/{task_id}/ or receive them by webhook. Results expire after one hour.

What are the Walter API rate limits?
By default, sync humanizer requests are limited to 3 per minute and sync detector requests to 10 per minute, with additional per-user and per-IP limits. Async requests aren't subject to the per-minute limits; they're constrained by credits and a pending-jobs cap that depends on your plan. Rate-limit responses include a Retry-After header.

How much does the Walter API cost?
Most text endpoints cost 1 credit per word. Monthly plans range from 300,000 credits for $49 to 25 million credits for $1,699, and new accounts get a 2,000-credit free trial for 5 days with no card required. Failed requests are refunded automatically.

Can I preserve keywords with the Walter API?
Walter's MCP documentation describes keyword, entity, and URL preservation for walter_humanize. The humanizer API reference documents the content field and async options. If you need specific phrases kept when using the API, verify them in your own code after each call, or use the MCP route for that workflow.

Can I use Walter MCP in Claude Code?
Yes. Run claude mcp add walter-writes https://mcp-server.walterwrites.ai/mcp -t http --scope user, then authenticate with /mcp. Claude Code can then run Walter on files in your repo and write the results back.

Which should I pick if I'm just getting started?
If you mainly want to check and humanize your own writing, start with MCP in the assistant you already use. If you're building something that other people will use, or something that runs without a person in the loop, start with the API and the free trial credits.

DEV Community