MCP Server

The OSO MCP server gives AI agents full access to the OSO data platform, including delegating data tasks to OSO agents, using the Model Context Protocol over Streamable HTTP. This empowers your agent to do anything you can do in the OSO app.

Property	Value
Server URL	https://mcp.oso.xyz/mcp
Transport	http (Streamable HTTP)
Authentication	Authorization: Bearer <YOUR_TOKEN>

Generate an API key

1. Log in to your account
2. Navigate to your organization's Settings → API Keys
3. Click "New Key +" and give it a descriptive name
4. Save your key immediately - you won't see it again

Detailed step-by-step instructions

1. Go to www.oso.xyz and log in
2. You'll be redirected to your organization dashboard
3. In the left sidebar, click the dropdown next to your organization name
4. Select "Settings"
5. Navigate to "Organization" → "API Keys"
6. Click "New Key +"
7. Enter a descriptive label (e.g., "Production API")
8. Copy and save your key immediately
9. Click "Create"

warning

Treat your token like a password — it grants full access to your OSO data. Never commit it to git or paste it into shared config.

Configure your agent

Claude Code

claude mcp add --transport http oso https://mcp.oso.xyz/mcp \
  --header "Authorization: Bearer ${OSO_TOKEN}"

Flag	Effect
--scope local (default)	This project only, just you
--scope user	Available across all your projects
--scope project	Written to a shared .mcp.json — commit it, but use an env var for the token

Verify with claude mcp list or the /mcp command inside a session. A healthy server shows as connected.

See the Claude Code MCP docs for more.

Codex CLI

codex mcp add oso --url https://mcp.oso.xyz/mcp \
  --bearer-token-env-var OSO_TOKEN

--bearer-token-env-var names an environment variable (here OSO_TOKEN) whose value Codex sends as the bearer token — set it in your shell before running the command. This writes an entry to ~/.codex/config.toml; you can edit it directly instead:

[mcp_servers.oso]
url = "https://mcp.oso.xyz/mcp"
bearer_token_env_var = "OSO_TOKEN"

Verify with codex mcp list, or type /mcp inside a Codex CLI session to see active servers.

See the Codex MCP docs for more.

OpenClaw

openclaw mcp set oso '{"url":"https://mcp.oso.xyz/mcp","transport":"streamable-http","headers":{"Authorization":"Bearer '"${OSO_TOKEN}"'"}}'

This writes to ~/.openclaw/openclaw.json; you can edit it directly instead:

{
  "mcp": {
    "servers": {
      "oso": {
        "url": "https://mcp.oso.xyz/mcp",
        "transport": "streamable-http",
        "headers": {
          "Authorization": "Bearer <YOUR_TOKEN>"
        }
      }
    }
  }
}

Add the entry to your workspace's .mcp.json instead of the gateway config if you only want one agent to have access. OpenClaw doesn't surface MCP connection failures in chat — check the gateway log if tools seem to be missing.

See the OpenClaw MCP docs for more.

Available tools

Once connected you'll have tools to explore and query the OSO Data Lake — listing datasets, inspecting schemas, and running SQL. Ask your agent "what OSO tools do you have?" to see the current set.

Troubleshooting

Symptom	Fix
401 Unauthorized	Token missing, expired, or malformed. Confirm the header is exactly Authorization: Bearer <token>.
Claude Code: not listed	Run claude mcp list to confirm it's registered; re-add with the correct --scope.
Codex CLI: not listed	Run codex mcp list; confirm [mcp_servers.oso] in ~/.codex/config.toml and that OSO_TOKEN is set in your shell.
OpenClaw: tools missing	MCP failures don't surface in chat. Check the gateway log, and confirm the entry in ~/.openclaw/openclaw.json (or workspace .mcp.json).

1. Check the server is reachable

curl -s -X POST https://mcp.oso.xyz/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer ${OSO_TOKEN}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

A successful response includes "serverInfo":{"name":"OSO Data Lake Explorer",...}.

2. Check your account is working

Once the server is connected in Claude Code, ask directly in a session:

check if the oso mcp is working

Claude will call an OSO tool and confirm whether your token has valid access.