Getting started

There are two ways to connect: point your assistant at the hosted remote server (no install, OAuth in the browser), or run the local stdio server against your own sandbox or live credentials. Most people want the first one.

The fastest path: the connect wizard

One command detects every supported AI client on your machine and wires each one to the remote Satchel MCP server — no cloning, no JSON to hand-edit, no keys to paste:

npx satchel-mcp connect

It will:

1. detect which of Claude Code, Cursor, Claude Desktop and Codex are installed;
2. ask which one(s) to configure (or configure all of them);
3. write the connection into each client's own config, backing up any existing file first;
4. for Codex, start the OAuth login explicitly (codex mcp login) — the other clients discover OAuth on first use, when you open a chat and the client asks you to approve the connection in your browser.

Flags: --dry / --dry-run previews what would be detected and written without touching any files; --url <url> points the wizard at a different server than the default hosted one.

Even faster: tell your agent to do it

If your AI assistant can edit its own MCP configuration, you can skip the terminal entirely — paste one line into its chat:

Help me add the Satchel MCP server: https://mcp.stchl.eu/mcp

Phrasing it as a request for help (rather than a direct command) means agents that can edit their own config just do it, and agents that can't (for example, claude.ai's web chat) explain where to add it instead of refusing outright.

Per-client setup, done manually

If you'd rather wire up one client by hand:

Claude Code

claude mcp add --transport http satchel https://mcp.stchl.eu/mcp

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "satchel": { "type": "http", "url": "https://mcp.stchl.eu/mcp" }
  }
}

Claude Desktop — its config file is stdio-only, so the remote HTTP server is reached through a small bridge process. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "satchel": { "command": "npx", "args": ["mcp-remote", "https://mcp.stchl.eu/mcp"] }
  }
}

(Claude Desktop's native path — Settings → Connectors — is the other option, without editing a config file at all.)

Codex — add to ~/.codex/config.toml:

[mcp_servers.satchel]
url = "https://mcp.stchl.eu/mcp"

Then run codex mcp login satchel to authenticate.

Whichever path you use, the first tool call opens an OAuth consent screen in your browser. Approve it, and your assistant is talking to a live-shaped sandbox account.

Running the local stdio server instead

The stdio server (mcp/) is the one to run when you want a local MCP server — for development, for pointing at your own sandbox instance, or for connecting directly to the live API with your own credentials (see Overview).

cd mcp && npm install
npm start        # runs `tsx src/index.ts` over stdio

Paste this into Claude Desktop's / Claude Code's / Cursor's MCP config, adjusting the path to where you cloned the repo:

{
  "mcpServers": {
    "satchel-mcp": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/satchel-mcp/mcp/src/index.ts"],
      "env": {
        "SATCHEL_BASE_URL": "http://localhost:3000/api/sandbox",
        "SATCHEL_USERNAME": "demo@satchel.mcp",
        "SATCHEL_PASSWORD": "satchel-demo-key",
        "SATCHEL_MODE": "sandbox"
      }
    }
  }
}

That configuration talks to a local sandbox — start it first:

cd app && npm install && npm run dev        # http://localhost:3000

Prove the whole thing works end to end:

cd mcp && node test-sandbox.mjs

See Configuration for the complete environment variable reference, and Sandbox reference for what the sandbox actually serves.

The waitlist

The landing page's sandbox flow issues a sandbox API key immediately — you don't wait for anything to try it. Requesting live access (a real Client Office account, not sample data) goes through a waitlist and onboarding process instead: a work email, a conversation with a Satchel account manager about the service and the information needed to assess an application. The applicable agreement, identification, verification and due diligence are required, and supporting documents may be requested. Only after those steps are completed and credentials are issued is the switch to live the same three-environment-variable change described in Overview.