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

Tool	What it does
search_datasets	Find datasets by name or column name
get_dataset_schema	Columns, types, statistics and sample rows
query_dataset	Run an OData v4 query; reads are capped at 200 rows
profile_column	The values a column actually holds, before you filter on one
lookup_sql_syntax	Confirm a function or statement exists in Opteryx SQL
validate_sql	Check SQL against the dialect and your schemas without running it
search_docs	Search the Opteryx documentation

Every call runs as the user the token belongs to.

Configuration

Variable	Default	Purpose
OPTERYX_USER	—	The user, if --user is not given
OPTERYX_TOKEN	Keychain entry opteryx-mcp / user	The personal access token
OPTERYX_MCP_URL	https://agent.opteryx.app/mcp/	MCP endpoint
OPTERYX_AUTH_URL	https://authenticate.opteryx.app	Where access tokens are minted

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.