opteryx-mcp

Connect Claude Desktop, Claude Code and other MCP clients to Opteryx. Ask questions about your data in plain English; the assistant finds datasets, reads schemas, queries, and checks Opteryx SQL, all as you and against only the data you can see.

uvx opteryx-mcp login --user <user>

Why a local bridge

The Opteryx MCP endpoint (https://agent.opteryx.app/mcp/) takes a bearer token, and access tokens last five minutes. A token pasted into a client's config stops working almost immediately. opteryx-mcp holds a user and a personal access token instead, exchanges them for a fresh access token a minute before each one expires, and forwards everything the client sends. It also re-mints if a token is rejected, and re-opens the MCP session if the server forgets it.

It has no dependencies beyond the Python standard library.

Setup

1. Create a personal access token

In Opteryx Studio, open Settings and create a personal access token. It looks like opt_..._01, lasts 90 days by default, and is shown once.

2. Store it

On macOS, login stores the token in the Keychain and checks it works. security prompts for the token, so it never appears in shell history:

uvx opteryx-mcp login --user <user>

Connected to https://agent.opteryx.app/mcp/ as <user>.
7 tools: search_datasets, get_dataset_schema, query_dataset, profile_column, lookup_sql_syntax, search_docs, validate_sql

Run it again to replace an expired token. On other platforms, set OPTERYX_TOKEN in the client's config instead.

3. Add it to your client

Claude Desktop. Print the config entry:

uvx opteryx-mcp config --user <user>

Then quit Claude Desktop (Cmd-Q) and merge the entry into ~/Library/Application Support/Claude/claude_desktop_config.json, keeping the file's other keys. Desktop rewrites that file when it quits, so an entry added while it is running is silently dropped. The entry looks like:

{
  "mcpServers": {
    "opteryx": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["opteryx-mcp", "--user", "<user>"]
    }
  }
}

uvx is named by absolute path because Desktop starts servers with a minimal PATH. Reopen Desktop and the server appears in a chat's + / tools menu, under Settings → Developer, and in Code-tab sessions.

Claude Code.

claude mcp add opteryx -- uvx opteryx-mcp --user <user>

Other clients. Any client that launches stdio servers takes the same command: uvx opteryx-mcp --user <user>.

Tools

Every call runs as the user the token belongs to.

Configuration

Troubleshooting

• uvx opteryx-mcp check --user <user> connects once and lists the tools, the same way a client would.
• Claude Desktop writes the bridge's log to ~/Library/Logs/Claude/mcp-server-opteryx.log. It records each token minted and every request that fails.
• token request failed (401) means the user and token don't match, or the token has expired or been revoked. Create a new one and run login again.
• If the server never appears in Desktop, check that the entry is still in the config file. If you edited it while Desktop was running, it was overwritten.

Development

pip install -e . pytest ruff
make test
make lint

Releases are published to PyPI from v* tags.