Soup.net — MCP Setup

What is MCP?

The Model Context Protocol gives AI agents direct tool access to Soup.net. Instead of browsing the web form, the agent calls check_recipe and get_briefing as native tools.

MCP works with Codex, Claude Code, Claude Desktop, and other MCP-compatible agents. See also: Anthropic’s extension guide, MCP quickstart.

Getting an API key

Log in to the Soup.net dashboard and generate a daily or scoped key. Daily keys rotate automatically. Scoped keys let you restrict access to specific recipe books with a custom expiry.

Two ways to connect

Chat-style AIs (claude.ai, ChatGPT, Mistral Le Chat, Perplexity) connect via OAuth — no API key to copy. Add https://mcp.soup.net/mcp as a custom connector, sign in to Soup.net, and choose which recipe books to share (and read vs. write for each) right in the consent screen. Per-client steps for each chat AI are at https://www.soup.net/info/connect.

Developer tools (Codex, Claude Code, Claude Desktop, VS Code, Google Antigravity, Cursor, Windsurf, Zed) use a Bearer API key — the options below. Most of these also accept the OAuth flow above if you’d rather sign in than paste a key; point them at https://mcp.soup.net/mcp and let their built-in OAuth client handle the rest.

Option 1: Codex

Codex uses config.toml, not .mcp.json. Use .codex/config.toml in a trusted project when the Soup.net key should stay scoped to that repo. Use ~/.codex/config.toml only when the same Soup.net identity should apply globally.

Recommended: keep the token in an environment variable available where Codex starts:

[mcp_servers.soupnet]
url = "https://mcp.soup.net/mcp"
bearer_token_env_var = "SOUPNET_API_KEY"

Set SOUPNET_API_KEY in Codex’s environment, then restart Codex or start a new session. Verify with /mcp in the TUI or codex mcp list.

This guidance was checked against Codex docs on 2026-05-16. If it fails, consult the OpenAI Developers docs MCP for current Codex MCP configuration.

If you prefer a self-contained project config and understand the secret-handling risk:

[mcp_servers.soupnet]
url = "https://mcp.soup.net/mcp"
http_headers = { Authorization = "Bearer YOUR_API_KEY" }

Do not commit a .codex/config.toml file that contains a token.

Option 2: Claude Desktop

Open Claude Desktop
Click the Claude menu (top menu bar) → Settings…
Go to the Developer tab → click Edit Config
Paste the config below into claude_desktop_config.json and save
Quit and restart Claude Desktop

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Important: Claude Desktop runs commands from C:\Windows\System32, so all paths in the config must be absolute.

macOS / Linux config

{
  "mcpServers": {
    "soupnet": {
      "command": "npx",
      "args": ["tsx", "/FULL/PATH/TO/soupnet/apps/mcp-server/src/index.ts"],
      "env": {
        "SOUPNET_BACKEND_URL": "https://mcp.soup.net",
        "SOUPNET_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Replace /FULL/PATH/TO/soupnet with the absolute path to your local soupnet repo.

Windows config

{
  "mcpServers": {
    "soupnet": {
      "command": "cmd",
      "args": ["/c", "npx", "tsx", "C:\\path\\to\\soupnet\\apps\\mcp-server\\src\\index.ts"],
      "env": {
        "APPDATA": "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming",
        "SOUPNET_BACKEND_URL": "https://mcp.soup.net",
        "SOUPNET_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Replace C:\\path\\to\\soupnet with the absolute path to your local soupnet repo, and YOUR_USERNAME with your Windows username. The APPDATA env var is needed because Claude Desktop doesn’t always expand %APPDATA% correctly.

After restarting, look for the MCP server indicator in the bottom-right of the chat input. Click it to verify check_recipe and get_briefing are listed.

Alternative: install via desktop extension (.mcpb)

If your Claude Desktop version supports extensions:

Download soupnet.mcpb
In Claude Desktop: Settings → Extensions → Advanced settings
Click Install Extension… and select the downloaded file
Enter your API key when prompted

This bundles the same MCP server as the manual config above. The extension stores your API key in the OS keychain.

Option 3: Claude Code (CLI)

Add this to .mcp.json in your project root (per-project) or ~/.claude/.mcp.json (global). Claude Code runs from the project directory, so relative paths work here:

macOS / Linux config

{
  "mcpServers": {
    "soupnet": {
      "command": "npx",
      "args": ["tsx", "apps/mcp-server/src/index.ts"],
      "env": {
        "SOUPNET_BACKEND_URL": "https://mcp.soup.net",
        "SOUPNET_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Windows config

{
  "mcpServers": {
    "soupnet": {
      "command": "cmd",
      "args": ["/c", "npx", "tsx", "apps/mcp-server/src/index.ts"],
      "env": {
        "SOUPNET_BACKEND_URL": "https://mcp.soup.net",
        "SOUPNET_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Available tools

Tool	Purpose
`check_recipe`	Check a recipe against Soup.net. Logs your recipe and returns similar recipes with evidence. Supports `clusters` and `max_chars` params for concise responses.
`get_briefing`	Returns the Soup.net briefing — recipe-check format, your recipe books, and a clustered sample of recipes from this user's corpus. Call this before your first check.

Uploading private files

The check_recipe tool accepts a file_url parameter for multimodal evidence (images, PDFs, audio, video). For files already public on the web, just pass the URL. For private local files — screenshots, generated artifacts, anything that lives only on your disk — upload them first via the POST /uploads REST endpoint, then pass the returned URL.

Why this two-step? MCP tool calls pass JSON arguments; binary content has to be base64-encoded inline, which blows the agent's context window on any meaningful image. The upload endpoint sidesteps this with a normal multipart POST, the same shape the Gemini File API uses for the same reason.

Step 1. POST your file to https://mcp.soup.net/uploads with your API key as a Bearer token:

curl -X POST https://mcp.soup.net/uploads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@/path/to/screenshot.png"

Response (200 OK):

{
  "ok": true,
  "file_url": "https://mcp.soup.net/uploads/9f3c2e1a-....png",
  "content_hash": "sha256-hex...",
  "mime_type": "image/png",
  "size_bytes": 184320
}

Step 2. Pass the returned file_url to check_recipe as the file_url parameter. The MCP server detects own-hostname URLs and reads the file directly — no second HTTP fetch.

Behavior and security

The URL is not publicly servable. A GET against https://mcp.soup.net/uploads/<id>.png always returns 404 — even from the uploading key. Treat the URL as an opaque reference token, not a download link. (Same model as Gemini File API file handles.)
Uploads are bound to the API key that created them. If a different key tries to use your uploaded URL, check_recipe returns the same "could not fetch" error as for a missing URL — no information leak about whether the upload exists.
When the API key expires or is revoked, its uploads become unreachable. The api key is the security boundary, not the user account. Plan key rotation accordingly: upload + check should happen within the same key's lifetime.
Supported MIME types: PNG, JPEG, WebP, MP4, MOV, MP3, WAV, FLAC, OGG, PDF. Max size 20 MB.
Rate limit: 100 uploads per hour per API key.

Troubleshooting

Server not appearing after restart

Verify your config JSON is valid (no trailing commas, correct quoting)
Check that Node.js is installed: node --version
Try running the server manually: npx tsx apps/mcp-server/src/index.ts
Claude Desktop logs:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Windows: %APPDATA%\Claude\logs\mcp*.log

ENOENT error on Windows

If the server fails with a path error referencing ${APPDATA}, add the expanded APPDATA path to your config’s env block (shown in the Windows config above).

Remote HTTP (deployed Soup.net)

If your Soup.net server is deployed (e.g., at mcp.soup.net), agents can connect over HTTP without running a local server. This is the recommended setup for production use.

Each MCP client has a distinct config schema. The blocks below are confirmed working — copy the one that matches your client. Don't mix schemas: the top-level key, URL field name, and required extras differ by client.

Codex (.codex/config.toml or ~/.codex/config.toml)

Use project-scoped .codex/config.toml for repo-specific Soup.net keys in trusted projects, or ~/.codex/config.toml only when the same key should apply everywhere.

[mcp_servers.soupnet]
url = "https://mcp.soup.net/mcp"
bearer_token_env_var = "SOUPNET_API_KEY"

Make SOUPNET_API_KEY available where Codex starts, then restart Codex or start a new session. Verify with /mcp or codex mcp list. Inline http_headers also works, but requires secret hygiene. Checked against Codex docs on 2026-05-16; if it fails, consult the OpenAI Developers docs MCP.

Claude Code (.mcp.json)

Per-project .mcp.json at the repo root, or ~/.claude/.mcp.json for global.

{
  "mcpServers": {
    "soupnet": {
      "type": "http",
      "url": "https://mcp.soup.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

One-liner equivalent: claude mcp add --transport http soupnet https://mcp.soup.net/mcp --header "Authorization: Bearer YOUR_API_KEY"

VS Code (.vscode/mcp.json)

Per-project .vscode/mcp.json. The top-level key is servers (not mcpServers), and inputs is required (use [] if you have no prompts).

{
  "servers": {
    "soupnet": {
      "url": "https://mcp.soup.net/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  },
  "inputs": []
}

Google Antigravity

User-global config at ~/.gemini/antigravity/mcp_config.json (Windows: C:\Users\<you>\.gemini\antigravity\mcp_config.json). Applies to all projects, not a per-project config. Restart Antigravity after saving. Antigravity also supports self-configuration — you can paste the block below into a chat and ask the agent to install it.

{
  "mcpServers": {
    "soupnet": {
      "serverUrl": "https://mcp.soup.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Note: Antigravity uses serverUrl (not url).

Claude Desktop (via mcp-remote)

Claude Desktop doesn't speak HTTP MCP natively yet — mcp-remote bridges stdio to HTTP.

{
  "mcpServers": {
    "soupnet": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.soup.net/mcp",
               "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}

Requires Node.js.

Web agents (no MCP)

Agents that can browse the web (ChatGPT, Google Stitch, etc.) can check recipes by visiting:

https://mcp.soup.net/check?key=YOUR_API_KEY

No MCP configuration needed. The web form is designed for AI agents that can fill HTML forms.

Bootstrap your agent

Copy-paste this into your AI agent’s system prompt or first message to bootstrap correct understanding. The agent’s own instructions carry more weight than anything in our system — this blurb sets the right mental model so the agent uses the tools correctly from the start.

You already work to understand my taste and judgment — Soup.net makes that understanding persistent and shared across my other agents and sessions. Recipe checks are read-only searches with an append-only logging side effect. Every check makes the corpus smarter for all my agents. There are no destructive operations, so check freely and often.

Recipes are from MY perspective (the human), not yours: "As a [my role] working on [my goal], I [prefer/chose] so that [reason]." Context scopes the judgment. Evidence supports the claim — my direct words, my artifacts, or external sources. Every claim and quoted reference needs to be true at the moment you submit.

For the full format with examples: call get_briefing (MCP) or visit /docs/recipe-check-guide (web).

Tips for agents

max_chars: 2000 keeps responses compact when context is tight. The briefing covers the rest.

Bootstrap your corpus

New to Soup.net? Your corpus starts empty. Bootstrap Your Corpus walks you through seeding it by extracting taste and judgment from your existing AI agent sessions. Pick a few diverse sessions for the best cross-pollination.