MCP server
Redgold exposes a Model Context Protocol server so an external MCP client — Claude Code or any other — can read your datasets and drive your own agent sessions without custom integration code. The server runs the read-only tenant tool profile: every call is scoped server-side to the account behind your API key.
Endpoint
POST https://api.redgold.ai/api/mcp
The transport is streamable HTTP. A client sends one JSON-RPC request per HTTP POST and receives the JSON-RPC response as application/json. The current protocol version is 2024-11-05.
Authentication
Send an sk-rg- key as a bearer token, the same credential the model API uses. See authentication for how to create one.
export REDGOLD_API_KEY=sk-rg-...
The edge resolves the key to your account and scopes every tool call to it. A request that does not resolve to an account is rejected with a JSON-RPC error:
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32001, "message": "unauthenticated: no verified caller" } }
Connect from Claude Code
Add the server with the CLI:
claude mcp add --transport http redgold https://api.redgold.ai/api/mcp \
--header "Authorization: Bearer $REDGOLD_API_KEY"
Or add it to .mcp.json directly:
{
"mcpServers": {
"redgold": {
"type": "http",
"url": "https://api.redgold.ai/api/mcp",
"headers": { "Authorization": "Bearer sk-rg-..." }
}
}
}
Any MCP client that speaks streamable HTTP connects the same way: point it at the endpoint and set the Authorization header.
Tools
The tenant profile exposes read-only dataset tools and a scoped view of your own agent sessions. Dataset tools operate only on datasets your account owns; agent tools operate only on your own tickets, sessions, and approvals.
Dataset tools
| Tool | Purpose | Arguments |
|---|---|---|
list_storage_datasets | List datasets in engine storage that you own. | — |
load_storage_dataset | Load one owned dataset from storage into the query engine. | name (required); columns, limit, filter (optional) |
query_datasets | List datasets currently loaded in the query engine, filtered to yours. | — |
query_schema | Column names and types of one owned dataset. | dataset (required) |
query_data | Run a read-only SQL query against one owned dataset. | sql (required), dataset (required in the tenant profile) |
A dataset name must resolve under your account's namespace. query_data will not fall back to "the first loaded dataset" on this surface — a dataset argument is required so a query can never run against another account's data.
Agent tools
| Tool | Purpose | Arguments |
|---|---|---|
list_agent_tickets | List your own tickets (open by default). | state, limit (optional) |
list_agent_sessions | List your own agent sessions and their status. | — |
tail_agent_session | Tail the recent stream of one owned session. Bounded to 500 lines / 30s. | session_id (required); max_lines, max_seconds (optional) |
agent_action_status | Poll the resolution of an approval you created. | approval_id (required) |
agent_spawn | Request a new agent session in your own d-pod. Approval-gated. | purpose (required); model, target_environment, resource_profile, agent_name, max_turns, max_spend (optional) |
agent_prompt | Send a prompt to an owned session. Approval-gated. | session_id, prompt (required) |
Worked calls
List the available tools:
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
Query one of your datasets:
{
"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {
"name": "query_data",
"arguments": { "dataset": "tenant/acme/prices", "sql": "SELECT symbol, close FROM prices ORDER BY ts DESC LIMIT 5" }
}
}
A tool result is returned as MCP text content:
{ "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "<query result rows>" } ] } }
List your open tickets:
{
"jsonrpc": "2.0", "id": 3, "method": "tools/call",
"params": { "name": "list_agent_tickets", "arguments": { "state": "open", "limit": 20 } }
}
Agent action approval flow
agent_spawn and agent_prompt never take effect directly. Each call creates an approval request attributed to your account and returns an approval id; the underlying action runs only after that approval resolves. Poll it with agent_action_status:
{
"jsonrpc": "2.0", "id": 4, "method": "tools/call",
"params": { "name": "agent_spawn", "arguments": { "purpose": "summarize yesterday's prices", "target_environment": "my-dpod" } }
}
The result carries the approval id; pass it to agent_action_status until it reports the action as resolved. The read tools (list_agent_tickets, list_agent_sessions, tail_agent_session, agent_action_status) are not approval-gated.
Scoping guarantees
Scoping is enforced on the server from the account resolved at the edge, never from an argument in the request. A tool call that names a dataset you do not own is refused:
{ "result": { "content": [ { "type": "text", "text": "Error: dataset 'tenant/other/x' is not owned by the caller" } ] } }
Listing tools (list_storage_datasets, query_datasets) return only your datasets. Agent tools read only your own tickets, sessions, and approvals even if an upstream service returns more.
Limits
The tenant profile is read-only apart from the two approval-gated agent actions. Operator and dev tools — task management, tmux, compilation, raw SQL against the whole database, and cluster operations — are not part of this surface and are unreachable with an sk-rg key. tail_agent_session is bounded to 500 lines and 30 seconds per call; there is no unbounded server push.
See authentication, errors, and limits.