Authentication and tool visibility

Send one existing RunHarvester key in either header:

Authorization: Bearer rh_live_...

X-API-Key: rh_live_...

If both headers are present, their values must be identical. Keys in the URL or query string are not accepted.

The key type controls the API family exposed to the agent:

tools/list includes only operations granted by the current key scopes. Every tool call resolves the key and checks its scope again, so revocation, expiry, and permission changes take effect without reconnecting.

To use both API families, configure the same /mcp URL twice under different names and use a Data key for one connection and a Browser Workflow key for the other.

Connect from Codex

Codex supports Streamable HTTP MCP servers and bearer tokens. Put each key in an environment variable, then add these entries to ~/.codex/config.toml or a trusted project's .codex/config.toml:

[mcp_servers.runharvester_data]
url = "https://api.example.com/mcp"
bearer_token_env_var = "RUNHARVESTER_DATA_API_KEY"
default_tools_approval_mode = "writes"
tool_timeout_sec = 45

[mcp_servers.runharvester_browser]
url = "https://api.example.com/mcp"
bearer_token_env_var = "RUNHARVESTER_BROWSER_API_KEY"
default_tools_approval_mode = "writes"
tool_timeout_sec = 45

Use codex mcp list or /mcp to verify the connections. See the Codex MCP configuration reference for the current client settings.

OpenAI Responses API

Remote MCP tools can be attached directly to a Responses request. Each server entry uses the same URL and a different key:

import OpenAI from 'openai';

const openai = new OpenAI();
const response = await openai.responses.create({
  model: 'gpt-5',
  input: 'List my recent scrape requests and summarize their status.',
  tools: [{
    type: 'mcp',
    server_label: 'runharvester_data',
    server_url: 'https://api.example.com/mcp',
    authorization: process.env.RUNHARVESTER_DATA_API_KEY,
    require_approval: 'always',
  }],
});

For a Browser Workflow task, use a second entry with another server_label and RUNHARVESTER_BROWSER_API_KEY. See the OpenAI MCP tools guide.

Generic Streamable HTTP client

Clients that support explicit headers can use a configuration shaped like:

{
  "mcpServers": {
    "runharvester-data": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${RUNHARVESTER_DATA_API_KEY}"
      }
    }
  }
}

Environment interpolation is client-specific. Do not put the literal secret in a committed configuration file.

Tools

The MCP server provides 27 RunHarvester API operations, plus connection-aware helpers. MCP clients can inspect the complete input schema for every available tool through tools/list.

Tool inputs follow the public RunHarvester API schemas. Path, query, and allowed header parameters are top-level snake_case fields, while JSON bodies remain under body. Browser project_id and environment_id are taken from the API key binding and cannot be overridden by the agent.

workflow_create_batch_manifest accepts typed admission fields and an items array. MCP clients can inspect the complete input schema for every available tool through tools/list.

Response envelopes

All successful tool calls return:

{ "ok": true, "status": 200, "data": {}, "meta": {} }

API errors set MCP isError and return a safe envelope:

{
  "ok": false,
  "status": 429,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request rate limit exceeded",
    "request_id": "..."
  },
  "retry_after": "1"
}

Only request ID, credit, rate-limit/retry, and route metadata headers can appear in meta.

Resources and bounded content

The server provides these resources or resource templates:

runharvester://contract/openapi
runharvester://data/requests/{id}/result/{part}
runharvester://browser/runs/{runId}/evidence/{evidenceId}/{expiresAt}/{signature}

data_get_result returns metadata and UTF-8 previews up to 4 KiB. Read retained html, text, data, or the full result with data_read_result_content: the default chunk is 16 KiB and the maximum is 64 KiB. Its opaque cursor is bound to the request and content part.

Screenshot evidence is MCP image content; masked HTML is text content. Existing signed-resource expiry and the 1 MiB screenshot limit remain enforced by the REST implementation.

Wait helpers poll once per second, default to 10 seconds, and accept at most 30 seconds. A non-terminal timeout is successful and includes timed_out: true plus retry_after_ms; MCP cancellation aborts the wait.

The MCP request body limit is 4 MiB. Manifests that exceed it must be uploaded through the REST API or SDK.

Verify the connection

After adding the MCP server, verify that the client can see it and ask the agent to call connection_info.

For Codex, run:

codex mcp list

You can also use /mcp in Codex to view connected servers and their available tools.

connection_info returns the API key type and granted scopes. For a Browser Workflow key, it also returns the bound workspace, project, and environment. The API key itself is never returned.

If an expected tool is missing, check that the connection uses the correct key type and that the key has the required scope.

Keep credentials safe