Skip to main content

Set up the MCP server for your coding assistant

warning

We recommend Claude Code. It's the client we've tested most thoroughly. The others below use the same MCP server and should work the same way, but they aren't fully tested yet — if you hit a snag with one of them, Claude Code is the safe fallback.

Where the package lives

The package is currently published on TestPyPI, not the main PyPI index. That's why every command below carries the TestPyPI index URL. When the package moves to PyPI, those extra flags can be dropped.

The commands below use uvx, which comes with uv and fetches and runs the server for you — there is no separate install step. pipx works too; see Plain pip if you would rather install the server yourself.

Claude Code​

Add an .mcp.json file to your project root. Paste this text in (or into ~/.claude.json so it applies to all your projects):

{
  "mcpServers": {
    "nuvei-mcp-builder": {
      "command": "uvx",
      "args": [
        "--index", "https://test.pypi.org/simple/",
        "--index-strategy", "unsafe-best-match",
        "nuvei-mcp-builder"
      ]
    }
  }
}

The server works without this, and you can skip it — but it is the better start, and it is one command. Run it in your project, before you open Claude Code:

uvx --index https://test.pypi.org/simple/ --index-strategy unsafe-best-match \
    --from nuvei-mcp-builder nuvei-mcp-builder-init

It does three things:

  • Writes the guides the agent follows (skills and rules) into your project.
  • Turns on the safety guardrails (hooks) that stop your Nuvei account details from being pasted into the chat, written to a file, or read back out.
  • Adds the slash commands, such as /design-app and /build-and-verify (see Commands).

Why before the session. Claude Code reads both the guardrails and the project guides when it starts up, so neither can be added to a session that is already running. Run the bootstrap first and the agent knows the correct order of steps from its very first turn, instead of discovering it by being refused.

Useful options:

  • --platform android or --platform ios picks the target platform yourself. Leave it out and your operating system decides (macOS → iOS, otherwise Android).
  • --no-hooks skips the safety guardrails.

The bootstrap never touches your credentials, and it records what it did in .nuvei/nuvei-mcp-builder.log.

Then start Claude Code and run /design-app — or just say "build me an app with Nuvei payments".

Codex CLI​

Codex configures MCP servers in TOML, not JSON. Paste this into ~/.codex/config.toml:

[mcp_servers.nuvei-mcp-builder]
command = "uvx"
args = ["--index", "https://test.pypi.org/simple/", "--index-strategy", "unsafe-best-match", "nuvei-mcp-builder"]

Because of the name Codex reports for itself, the guides are written to <project>/.codex/ instead of <project>/.agents/. Everything else works the same.

Cursor / Windsurf / Cline / Zed​

Same shape, in each editor's mcp.json:

{
  "mcpServers": {
    "nuvei-mcp-builder": {
      "command": "uvx",
      "args": [
        "--index", "https://test.pypi.org/simple/",
        "--index-strategy", "unsafe-best-match",
        "nuvei-mcp-builder"
      ]
    }
  }
}

Plain pip​

If you prefer to install the server yourself:

pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    nuvei-mcp-builder

--extra-index-url is required because the server's own dependencies (mcp and keyring) only exist on the real PyPI.

Then point your client at the installed program instead of uvx:

{
  "mcpServers": {
    "nuvei-mcp-builder": { "command": "nuvei-mcp-builder" }
  }
}
note

Restart all coding agent sessions for the new server to be picked up.

After adding or changing Nuvei credentials

The server keeps your credentials in memory once it has read them. The first time you add them is detected automatically, but adding another environment or changing a secret afterwards needs a client restart so the server picks up the new values.