MCP Server

The OSO MCP server lets AI agents query the OSO Data Lake directly using the Model Context Protocol over Streamable HTTP.

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

Before you start

Get your API token from the OSO dashboard under Settings → API Keys. Make sure you are in the right organization.

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.

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.

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.

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.