Connect your agent

Developer documentation

API & MCP documentation

DistroChef exposes the same project, opportunity, run, and handoff workflow through a JSON API and an MCP server.

MCP setup guide →

Authentication

Both interfaces require an OAuth 2.0 bearer token. Supported scopes are projects_read and projects_write. Register public clients at POST /oauth/register; authorization-code and refresh-token grants are supported.

Authorization: Bearer <access_token>
Idempotency-Key: <optional-client-generated-key>
X-Request-ID: <optional-request-id>

OAuth discovery metadata is available at /.well-known/oauth-authorization-server. Protected-resource metadata is available for /api and /mcp.

HTTP API

All API endpoints are JSON endpoints under /api. Write operations require projects_write; read operations require projects_read.

POST /api/projects
POST /api/projects/:id/analyze
POST /api/projects/:id/evaluate_opportunities
GET  /api/projects/:project_id/opportunities
GET  /api/projects/:project_id/facts
POST /api/opportunities/:opportunity_id/runs
GET  /api/runs/:id
POST /api/runs/:id/cancel
GET  /api/runs/:run_id/handoffs
POST /api/runs/:run_id/steps/:id/retry
POST /api/handoffs/:id/resolve

MCP

Connect an MCP client to POST /mcp using Streamable HTTP. The server is stateless and exposes these tools:

Quick setup

Choose your agent, follow its setup instructions, and complete the browser sign-in when prompted.

Run this in your terminal:

The connection is shared by the Codex CLI and IDE extension.

codex mcp add distrochef --url https://distrochef.com/mcp
codex mcp login distrochef --scopes projects_read,projects_write
codex mcp list

Complete the browser sign-in when prompted, then check that DistroChef appears in your MCP server list.

The sign-in redirects to a temporary 127.0.0.1 callback. Run the login command on the same computer as the browser and keep it running until it reports success. A browser on another computer cannot reach that callback.

Run this in your terminal:

User scope makes DistroChef available from every Claude Code project.

claude mcp add --transport http --scope user distrochef https://distrochef.com/mcp
claude mcp login distrochef
claude mcp list

Complete the browser sign-in when prompted, then check that DistroChef appears in your MCP server list.

The sign-in redirects to a temporary 127.0.0.1 callback. Run the login command on the same computer as the browser and keep it running until it reports success. A browser on another computer cannot reach that callback.

Add this to .cursor/mcp.json:

Use .cursor/mcp.json for this project, or ~/.cursor/mcp.json to make DistroChef available across projects. Merge the entry into mcpServers if the file already exists.

{
  "mcpServers": {
    "distrochef": {
      "url": "https://distrochef.com/mcp"
    }
  }
}

Open Cursor’s MCP settings and connect DistroChef. Complete the browser authorization when prompted, then enable its tools in Agent chat.

Cursor setup reference →

Add this to .vscode/mcp.json:

In a VS Code workspace, create .vscode/mcp.json. Merge the entry into servers if the file already exists. You can also use the MCP: Add Server command and choose HTTP.

{
  "servers": {
    "distrochef": {
      "type": "http",
      "url": "https://distrochef.com/mcp"
    }
  }
}

Start DistroChef from the MCP configuration or MCP: List Servers. Complete browser authorization when prompted, then select its tools in Copilot Chat’s Agent mode.

VS Code setup reference →

Run this in your terminal:

Grok Build is the coding agent that uses the grok CLI. Add DistroChef as a remote HTTP server.

grok mcp add --transport http distrochef https://distrochef.com/mcp
grok mcp list
grok mcp doctor distrochef

Start Grok Build with grok. OAuth opens a browser on first use; you can also open /mcps and authenticate DistroChef there.

Grok Build setup reference →

Then try

Replace the example URL with your product’s homepage.

Use DistroChef to analyze https://example.com and show me the ranked distribution opportunities.

Agent skill

Give an agent the shareable skill for setup guidance, browser-capability requirements, safety boundaries, and copy-ready prompts.

Open DistroChef SKILL.md →

Available tools

create_project list_projects analyze_project get_project_facts list_opportunities get_opportunity start_run get_run get_next_steps report_step_result retry_step resolve_handoff cancel_run

Typical workflow

  1. Create or list a project, then analyze it to refresh facts and opportunities.
  2. Inspect an opportunity and start a run for an executable opportunity.
  3. Call get_next_steps with the caller’s runtime capabilities.
  4. Report the result with evidence, a failure, or a human handoff request.
  5. Resolve handoffs, retry failed steps when appropriate, or cancel the run.

Runtime capabilities

Opportunity and Run payloads include execution_requirements. Inspect it before execution, configure the current runtime, and pass only currently available capabilities to get_next_steps. Missing capabilities return setup guidance in the structured error.

{
  "capabilities": {
    "browser": true,
    "http": true,
    "repo_read": false,
    "repo_write": false
  }
}

Browser execution

  • Use a browser session the human can access and preserve it across authentication handoffs.
  • Never request or expose passwords, session cookies, recovery codes, or secrets.
  • Do not bypass CAPTCHA or MFA; request an otp_or_captcha handoff.
  • Request approval before account creation, payment, or external publication.
  • Verify the required receipt or public outcome instead of treating a click as success.

Reliability and errors

Use an idempotency key on retryable write operations. Responses include a request ID; structured errors include a code, message, optional details, and request ID. Runs cooperate with cancellation, and execution steps have server-enforced timeout deadlines.