MCP server

Redgold exposes a hosted MCP server over Streamable HTTP. Connect once to discover API operations, read and write data, and run reviewed pipelines. Every request validates the account credential, workspace membership and current grants. Paid data work uses prepaid admission with a caller-supplied charge ceiling.

This is one of the ways to connect an existing agent. The setup prompt installs local binaries and skills instead. Either path can keep the client's existing model provider. The RAC command guide maps CLI workflows; MCP calls use the declared API operations rather than CLI commands.

The free data skill bundle includes setup, query, transformation and hosting references plus a stdlib client. Download its checksum, verify it, and extract the redgold-data folder into your agent's skill directory.

Endpoint and authentication

No local Redgold binary is required. In your agent's MCP settings, choose an HTTP server, enter the URL below, and configure the Authorization header with your account API key. Keep the key in the client's secret configuration.

POST https://api.redgold.ai/api/mcp
Authorization: Bearer <scoped sk-rg key>
Content-Type: application/json
Accept: application/json, text/event-stream

Create a key through authentication. Keep it in your client's secret configuration. An optional x-redgold-tenant selects a workspace; a workspace-bound key cannot select another workspace. Personal scope remains available when the key has no workspace binding. Operator service tokens cannot invoke this customer profile.

Supported MCP versions are 2025-06-18, 2025-03-26 and 2024-11-05. Send initialize, then notifications/initialized, then tools/list or tools/call. Notifications receive an empty HTTP 202. Subsequent requests carry the negotiated MCP-Protocol-Version. Responses use JSON; this stateless profile does not require an SSE session. Requests are bounded to 256 KiB and responses to 1.5 MiB.

claude mcp add --transport http redgold https://api.redgold.ai/api/mcp \
  --header "Authorization: Bearer $REDGOLD_API_KEY"

Make REDGOLD_API_KEY available in your terminal before running this command; the shell expands it into the client's stored header. Treat that client configuration as a secret. Restart or reconnect your agent if it does not discover the server immediately. Ask it: “Search the Redgold API for build jobs, describe the create and status operations, and show me the required inputs.” Discovery executes no build.

For Codex, add the following to ~/.codex/config.toml and make REDGOLD_API_KEY available in the environment that starts Codex. The configuration refers to the variable name and does not store its value:

[mcp_servers.redgold]
url = "https://api.redgold.ai/api/mcp"
bearer_token_env_var = "REDGOLD_API_KEY"

See the official OpenAI documentation for MCP for Codex's HTTP transport, environment-backed headers and connection settings.

For other MCP clients, use these connection settings:

An HTTP 401 means the key is missing or invalid. HTTP 403 means the selected account, workspace or operation is not permitted. Discovery lists declared operations for this deployment plane; it does not grant access to them.

API tools

The API directory is compiled from pipeline route manifests and the gateway's checked route inventory. Route additions become discoverable when the MCP server containing those declarations is published. It covers the declared API counterparts used by rac and rci, including forge and search operations, remote build jobs and their status operations. The public endpoint lists public routes; the separately configured operator deployment can also list internal routes. A route declaration does not prove its backing service is currently available. Internal routes that rely on network trust instead of caller authentication require their native operator transport and cannot be invoked through MCP.

For example, call api_search with {"query":"build jobs"}, then pass a returned operation_id to api_describe. Supply exactly that operation ID to api_call; there is no arbitrary URL or shell-command execution. Request and response schemas come from the native registry when available. A null schema explicitly means the declaration has no registered native schema; mined parameters may be incomplete, and the underlying API validates every request.

Calls forward the caller's account and selected workspace to the ordinary API. They do not install an operator credential or bypass authorization, approvals or spending rules. Existing data tools below remain available, including their prepare/quote/run workflow.

For long work, submit through an existing job API, retain its job/run identifier, then use its status/results operations. The MCP adapter does not turn a synchronous endpoint into a durable job. Calls have one deadline of 1–120 seconds (30 by default) and a 1.5 MiB response bound. A timeout, interrupted response or oversized result can leave a mutation's outcome unknown. Reconcile through its status API and stable idempotency key before retrying; the adapter never automatically retries mutations. Forwarded response metadata includes HTTP status, content type, location, retry-after and etag when present.

Responses identify body_encoding as json, text or base64; binary bytes are preserved as base64. Large downloads need a smaller range header or the native download API. For binary uploads, send body_base64 with content_type instead of body. Wildcard-method operations require an explicit method; a fixed method cannot be overridden. Only declared prefix operations accept path_suffix.

SSE reads return a bounded text window with complete: false if the upstream stream is still open at the deadline. Such a window can end mid-event; it is not proof that the underlying operation completed. Use the native streaming client for continuous subscriptions. The last-event-id header is accepted for APIs that support resumption; the adapter does not invent a cursor or replay calls. WebSocket operations are discoverable but require their native transport. Commands that depend on a local checkout, terminal, filesystem or local credentials need a remote API equivalent or a local rac installation.

Data tools

tools/list returns JSON Schema generated from the checked-in native request types. Use it and data_describe for the exact input contract.

Dataset names come from discovery and use the existing engine ownership and workspace policies. Shared datasets need an explicit service allowlist; existing ingested data is not automatically licensed for resale. Arbitrary code, sinks and schema registration are outside the data-tool contract. The compatibility names list_storage_datasets, query_datasets, query_schema, query_data and load_storage_dataset delegate to this same DES boundary. Paid query/load aliases require a stable idempotency_key; their returned run is inspected through status/results. No alias creates a process-local cache. Agent and infrastructure API operations, when declared for the selected deployment, use the API tools above and retain their own authorization and approval policies.

Results and spending

A tool result contains a short content summary and the native JSON projection in structuredContent. Rejected tool calls set isError: true and include a stable error code, retryability and a next action. Authentication failures return HTTP 401 or 403 before effects.

A prepared plan binds its exact spec, schema, grant and price revisions. It expires after 15 minutes. Preparation executes no supplier calls, data writes or schedule activation. Execution reserves the quote before effects, and settles integer micro-USD (1000000 = USD 1) from durable usage. Search child receipts consume the parent reservation without a second account debit.

Use the same idempotency_key after a lost response. Changed parameters require a new plan and key. Poll status instead of repeating supplier calls. uncertain retains its reservation until the original receipt can be reconciled. complete: false describes a partial or rejected result; a partial summary is never committed as a complete output. Result pages expire after 24 hours.

Limits separately cover materialized source rows/bytes, execution time, cooperative memory enforcement, output bytes/rows, retained payload bytes, concurrency and charge. An output limit is not a scan limit. These limits do not represent physical disk-I/O caps or hard process preemption. Retained payloads currently have a quota and one-time byte charge rather than a duration-based storage charge.

Recurring execution

Hosting requires an interval and explicit daily/monthly spending allowances. Deployment performs a real paid smoke run and checks the scheduler binding, then returns ready_paused. activate is a separate requested action. Deploy, activate, pause and rollback require stable control idempotency keys. Credit exhaustion disables future admissions. A retry of rollback selects the same generation; rollback never reverses data already emitted.

See query data via MCP and run a pipeline via MCP. The distributable redgold-data skill includes authenticated setup, current workflows and a bounded stdlib client. Commercial listing and retail-rate approval remain separate launch steps.

The reviewed change-monitor hosting template compares complete snapshots of an accessible dataset; partial scans preserve its prior baseline. research-endpoint serves bounded pages of a fixed hosted plan's latest complete committed run. Discover them with data_catalog kind host_template, inspect their native schema, and set template at host preparation. Consumers use pipeline_host action results or POST the same arguments to /api/agent/data/pipeline_host with ordinary account authentication. Responses distinguish the latest attempt from the last complete result and retain result expiry and provenance. Browser collection remains with the separately authorized browser service.