Skip to content

Claude Code, Cursor, VS Code, Codex, Gemini CLI

In short

  • These clients run on your machine and speak MCP over HTTP, so a ParleML on localhost works directly.
  • Each needs the MCP address (http://localhost:8000/mcp on a local install) and a token from Settings → Access (Connect your agent).
  • Settings → Access → Your own agent shows each configuration below with your address and token filled in. Copy it from there.
  • Keep the token out of files a repository might commit. The examples read it from the PARLEML_API_TOKEN environment variable where the client supports that.

In the examples, replace <your-token> with the token you created, and http://localhost:8000 with your ParleML address if it differs.

Claude Code

  1. Add ParleML as an MCP server. Run this once in a terminal (it works in bash and PowerShell):

    claude mcp add --transport http parleml http://localhost:8000/mcp --header "Authorization: Bearer <your-token>"

    The server is added for the current folder only. To use ParleML in every project, add --scope user after add:

    claude mcp add --scope user --transport http parleml http://localhost:8000/mcp --header "Authorization: Bearer <your-token>"

  2. Start Claude Code with claude and type /mcp. parleml is listed as connected, with its tools.

  3. Ask What workspaces do I have in ParleML?

claude mcp add keeps the token in your Claude Code settings, not in the project folder. To change the token, run claude mcp remove parleml (with the same --scope), then add it again.

Claude Code also reads the ParleML skill packs directly. With both present, the skills use the MCP tools. The Claude Code tutorial walks through a first task.

Cursor

Put this in .cursor/mcp.json in the project, or in Cursor's global MCP settings. Cursor fills ${env:PARLEML_API_TOKEN} from your environment:

{
  "mcpServers": {
    "parleml": {
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer ${env:PARLEML_API_TOKEN}" }
    }
  }
}

Cursor also loads the skill pack from .cursor/skills/. Export it from Settings → Skill packs with Export with APM (Skills & packaging).

VS Code (Copilot agent mode)

Put this in .vscode/mcp.json. VS Code uses a top-level servers object and "type": "http":

{
  "servers": {
    "parleml": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer ${env:PARLEML_API_TOKEN}" }
    }
  }
}

Start VS Code from an environment that has the token, then start the server from the MCP configuration editor. The tools appear in the agent's tool picker. The VS Code MCP reference covers user-level configuration and secret inputs.

Codex

Put this in ~/.codex/config.toml. Codex reads the token from the environment variable that bearer_token_env_var names, so the file holds no secret:

[mcp_servers.parleml]
url = "http://localhost:8000/mcp"
bearer_token_env_var = "PARLEML_API_TOKEN"

Gemini CLI

Put this in ~/.gemini/settings.json, or .gemini/settings.json in a project. httpUrl selects streamable HTTP, and Gemini CLI fills ${PARLEML_API_TOKEN} from your environment:

{
  "mcpServers": {
    "parleml": {
      "httpUrl": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer ${PARLEML_API_TOKEN}" }
    }
  }
}

Type /mcp in the CLI to list the server and its tools. The skill pack is also a Gemini CLI extension (Skills & packaging).

Set the token variable

For the clients that read PARLEML_API_TOKEN, set it before you start the client.

macOS / Linux:

export PARLEML_API_TOKEN=<your-token>

Windows (PowerShell):

$env:PARLEML_API_TOKEN = "<your-token>"

To keep it across sessions, put the line in your shell profile, or on Windows use System Properties → Environment Variables.

Local server (stdio)

Some clients only start local MCP servers. The MCP server can also run as a local process that the client starts and talks to over standard input and output (stdio). It still calls the running ParleML for every answer.

With ParleML running in Docker under the name parleml, the client starts the server inside the container:

{
  "mcpServers": {
    "parleml": {
      "command": "docker",
      "args": ["exec", "-i", "-e", "PARLEML_API_TOKEN=<your-token>", "parleml", "python", "-m", "parleml_mcp.server"]
    }
  }
}

With sign-in off (open mode), you can leave out "-e", "PARLEML_API_TOKEN=<your-token>",. The config holds the token, so keep the file private.

Details: stdio from a ParleML source checkout

From a checkout, run uv sync first, then point the client at it. Settings → Access → Your own agent → Local (stdio) shows this entry with your address and token filled in:

{
  "mcpServers": {
    "parleml": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/parleml", "python", "-m", "parleml_mcp.server"],
      "env": { "PARLEML_API_BASE": "http://localhost:8000", "PARLEML_API_TOKEN": "<your-token>" }
    }
  }
}

Replace /path/to/parleml with the absolute checkout path. On Windows use forward slashes, such as C:/src/parleml, or escape the backslashes.

Tool results carry ui_url links into the ParleML app. In the Docker image the app and /mcp share one origin, so the links work with no setup.

In local development they don't: the app runs on Vite at http://localhost:5173, while http://localhost:8000 serves the API and /mcp but no pages. Point the links at the app with PARLEML_PUBLIC_URL:

  • Hosted /mcp: set it in the backend's environment before you start the backend.

    $env:PARLEML_PUBLIC_URL = "http://localhost:5173"
uv run uvicorn app.main:app --reload --app-dir backend --timeout-keep-alive 75

  • Stdio: add "PARLEML_PUBLIC_URL": "http://localhost:5173" to the server entry's env.

It must be an absolute http(s) URL, or the server refuses to start. It moves only the links: OAuth discovery stays on the backend, whose issuer is PARLEML_OAUTH_ISSUER when set, else the origin the client called.

Next