# Hydracept MCP server

> Lets AI agents discover capabilities, submit durable jobs, and retrieve artifacts and receipts through one hosted execution API.

- Repository: https://github.com/zencodeinc/hydracept-public
- Page: https://hostedmcp.org/servers/zencodeinc/hydracept-public
- Transport: stdio, remote
- Stars: 0
- License: MIT
- Latest version: 0.5.7

## Install

### Claude Code

```sh
claude mcp add --env 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' hydracept-public -- uvx hydracept
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "hydracept-public": {
      "command": "uvx",
      "args": [
        "hydracept"
      ],
      "env": {
        "HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "hydracept-public": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "hydracept"
      ],
      "env": {
        "HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"hydracept-public","type":"stdio","command":"uvx","args":["hydracept"],"env":{"HYDRACEPT_API_KEY":"<YOUR_HYDRACEPT_API_KEY>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "hydracept-public": {
      "command": "uvx",
      "args": [
        "hydracept"
      ],
      "env": {
        "HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add hydracept-public --env 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' -- uvx hydracept
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.hydracept-public]
command = "uvx"
args = ["hydracept"]

[mcp_servers.hydracept-public.env]
HYDRACEPT_API_KEY = "<YOUR_HYDRACEPT_API_KEY>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' hydracept-public uvx -- hydracept
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "hydracept-public": {
      "command": "uvx",
      "args": [
        "hydracept"
      ],
      "env": {
        "HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `HYDRACEPT_API_KEY` | yes | yes | Hydracept API key from https://hydracept.com/start (or use project secrets after init). Stdio only — the hosted remote uses OAuth, not this key. |
| `HYDRACEPT_MCP_TOOL_PROFILE` | no | no | Stdio MCP tools/list for the process lifetime: full (default when unset) or compact (eleven lifecycle tools). Hosted POST /mcp defaults to compact for new API keys; POST /mcp/full always lists all specialists. The registry remote (/mcp/claude) is the directory-safe OAuth surface. |

## Tools (45)

- `hydracept_capabilities`: Browse or fetch capability descriptors (keys, modes, schemas). Use resolve_capability when routing from intent alone. List/resolve is keyless; a bearer key may add project-scoped fields. No charge. Read-only.
- `hydracept_quote_capability`: Preview what a run would cost — does not execute, create a job, or charge the wallet. Use before spending when the user asks about price; use hydracept_run or hydracept_submit_job only to execute. Not the same as request_capability_quote on the full profile (human-paid capability commission). Requires bearer API key. No charge for the quote itself.
- `hydracept_invoke`: POST /v1/capabilities/{key}/invoke: synchronous capability call (no job poll loop). Use only when the capability descriptor lists invoke_sync; use hydracept_run for job-based execution and hydracept_pinned_run for exact model pins. Auth: bearer required. Cost: billed like invoke admission. Side effects: may create invoke audit records.
- `hydracept_cancel_job`: Request cancellation of one job. Use only when the user explicitly asks to cancel the job itself; stopping a local polling loop is not a cancellation. Returns whether the request was accepted, whether the job is already terminal, and the next action. Never promise that upstream provider work stopped or that already-incurred cost is refunded. Safe to retry: a terminal job reports its terminal state. Requires bearer key.
- `hydracept_get_receipt`: Read billing and provenance for a finished job. Does not run capabilities or spend money. Use after terminal success; use hydracept_job_status while still running. Hosted MCP accepts job_id only. Requires bearer key. No charge.
- `hydracept_download_artifact`: Fetch artifact metadata (and SHA-256 on hosted MCP) for a succeeded job output. Stdio may also write bytes when output_path is set. Requires bearer key. No charge on hosted.
- `hydracept_smoke`: Runs one REAL paid image.generate.v1 job (trial credit if eligible, otherwise wallet-billed like hydracept_run) — not a dry run or quote. Use only when the user explicitly wants a managed-trial smoke execution; never for price checks (hydracept_quote_capability) or catalog questions. Auth: bearer required. Cost: paid image generation. Side effects: creates job/receipt and provider usage.
- `hydracept_pinned_run`: POST /v1/inference/pinned: one exact provider/model pin with scientific receipt. Use for pinned inference experiments; use hydracept_run for registry capability keys. Optional processing=deferred for 50% Flex pricing when supported; no Flex→Standard fallback; capacity 429s may retry inside the admission deadline. Auth: bearer required. Cost: paid — hold at worst-case then settle at actual cost. Side effects: creates pinned receipt.
- `hydracept_pinned_bulk`: POST /v1/inference/pinned/bulk: concurrent pinned items (one execution each). Use for batch pins; use hydracept_pinned_run for a single pin. Auth: bearer required. Cost: billed per item. Side effects: creates bulk run state.
- `hydracept_pinned_get`: GET /v1/inference/pinned/{receipt_id}: fetch pinned run receipt. Use after hydracept_pinned_run; use hydracept_get_receipt for capability jobs. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_pinned_bulk_get`: GET /v1/inference/pinned/bulk/{bulk_id}: poll bulk pinned run aggregate. Use when hydracept_pinned_bulk returns nextAction poll. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_manifest_create`: POST /v1/provenance/manifests: hash receipt ids into a manifest id. receiptIds is required. Accepts capability-job receipts (rcp_… from hydracept_get_receipt) and pinned inference receipts. Verify with hydracept_manifest_verify. Auth: bearer required. Cost: none. Side effects: creates manifest record.
- `hydracept_manifest_verify`: POST /v1/provenance/manifests/{manifest_id}/verify: check manifest members. Read-only verification. Use after hydracept_manifest_create. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_lockfile_emit`: GET /v1/provenance/lockfile?receipt_id=: emit lockfile JSON for a receipt. Accepts capability-job receipts from hydracept_get_receipt and pinned inference receipts; verify with hydracept_verify_lockfile. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_verify_lockfile`: POST /v1/provenance/lockfile/verify: validate lockfile document. Use after hydracept_lockfile_emit or for CI replay. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_jobs_find`: Find a prior job in the bound project when you do not have its id. intent is recent, failed, or reusable. The list never includes prompt text. Use after context loss, for failure triage, or to recover a job to cancel. Requires bearer key. No charge. Read-only.
- `hydracept_job_inspect`: Read one prior job, including the prompt that was executed. executedPrompt is that prompt, also stored at requestSnapshot.input.prompt. Text jobs return it when a prompt record was kept and no input payload was stored. Also returns error, diagnostics, receipt summary, and a reuse candidate. Pass job_id from hydracept_jobs_find or an earlier run. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_project_status`: Read login-persistent project up status from local checkout (stdio, cwd=project). Side effects: none.
- `hydracept_project_up_install`: Run project up --install locally (stdio). Side effects: local install argv.
- `hydracept_surface_apply`: Apply surface JSON to project checkout (stdio). Does not grant allowlist by itself.
- `hydracept_project_sync`: Sync operations allowlist from tools/hydracept/manifest.json (stdio). Side effects: rewrites allowlist file.
- `hydracept_project_watch_once`: Execute pending project operations once (stdio). Side effects: local argv execution.
- `hydracept_project_request_operation`: POST /v1/projects/{projectId}/operations: enqueue a project operation for local execution. command status is read-only and available before any allowlist sync. Hosted MCP does not run argv; stdio watch_once/up executes. Auth: bearer required. Side effects: creates operation record.
- `hydracept_project_get_operation`: GET /v1/projects/{projectId}/operations/{id}: poll operation status. Use after hydracept_project_request_operation. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_ui_submit_job`: Panel submit job; same execution as hydracept_submit_job.
- `hydracept_ui_poll_job`: Panel poll job once; same API projection as hydracept_job_status.
- `hydracept_ui_download_artifact`: Panel save artifact into workspace (stdio App).
- `hydracept_ui_artifact_preview`: Panel bounded artifact preview (stdio App). Read-only media preview.
- `hydracept_ui_quote`: Panel quote adapter; same primitive as hydracept_quote_capability.
- `hydracept_ui_run`: Panel run adapter choosing invoke vs jobs from descriptor executionModes.
- `hydracept_ui_connect_project`: Panel init/connect flow (stdio App). Does not replace python -m hydracept init binding writes.
- `hydracept_ui_connection_recheck`: Panel read-only connection/runnability recheck. No secret arguments.
- `hydracept_ui_approve_job`: Panel POST /v1/jobs/{id}/approve (stdio App). Same API as human approval gate.
- `hydracept_ui_reject_job`: Panel POST /v1/jobs/{id}/reject.
- `hydracept_ui_select_variant`: Panel POST /v1/jobs/{id}/variants/select.
- `hydracept_ui_cancel_job`: Panel POST /v1/jobs/{id}/cancel. Side effects: cancels job when policy allows.
- `hydracept_ui_promote`: Panel apply_surfaces(path) locally; cloud never writes git checkout.
- `hydracept_run`: Run a capability (paid). Use when the user wants execution — not for quotes (hydracept_quote_capability), status (hydracept_job_status), or receipts (hydracept_get_receipt). Default wait=true waits until the job finishes; use hydracept_submit_job when this call must return immediately. Picks invoke vs durable job from the capability descriptor. Requires bearer key. Settles at actual provider cost plus any managed service fee; no per-call minimum. May create jobs, artifacts, and provider usage.
- `hydracept_submit_job`: Start a capability job and return its id immediately (paid). Use when execution is required but this MCP call must not block — not for quotes or status checks. Prefer hydracept_run when waiting is acceptable. Poll with hydracept_job_status. Same billing as hydracept_run. Requires bearer key.
- `hydracept_job_status`: Read one job's current status. Use after hydracept_submit_job or hydracept_run with wait=false; use hydracept_get_receipt after success. If the job id is unknown, use hydracept_jobs_find first. Requires bearer key. No charge.
- `hydracept_interaction_surface`: Present Hydracept App UI resource (stdio). Use when init/onboarding returns present_and_yield. Auth: workspace session. Side effects: UI presentation only.
- `resolve_capability`: Match the user's goal to a capability key using natural language. Use when the key is unknown; use hydracept_capabilities when you already have a key or need the catalog. Keyless. No charge. Read-only.
- `request_capability_quote`: POST /v1/capability-requests then submit: human-paid commission quote for a missing capability. summary is required. Not retail execution pricing (see hydracept_quote_capability). quoteId from this flow must not be used as execution.quoteId on jobs. Auth: bearer required. Cost: none to the agent (humans pay commission). Side effects: creates request rows.
- `get_capability_request_quote`: GET /v1/capability-requests/{id}/quote: read commission quote for an existing request. Returns status pending when a human has not priced it yet; that is not a 404. Use after request_capability_quote; not for retail hydracept_quote_capability. Auth: bearer required. Cost: none. Side effects: none.
- `hydracept_status`: Check workspace/session authentication and readiness, plus common setup errors. Use when setup, auth, or project binding is in doubt; use hydracept_job_status for a specific execution. Does not execute capabilities or spend money. Hosted requires bearer (WORKSPACE_KEY_REQUIRED when missing); stdio checks local project binding. Not a substitute for hydracept_capabilities.

## FAQ

### How do I connect Claude Code or Cursor to Hydracept MCP?

Run the init command to bind MCP to workspace secrets, then serve the stdio server or use the hosted MCP endpoint with a bearer API key. The agents install command adds the Cursor or Claude Code plugin.

### How much does Hydracept cost?

There is a free plan for individuals, and paid plans add capacity. BYOK carries no Hydracept fee, while managed inference costs provider price plus a 6% service fee.

### How do I generate an image with Hydracept?

Run the image.generate.v1 capability with a prompt, either via the CLI one-shot command or the Python SDK by submitting a capability job.

### Which languages and SDKs does Hydracept support?

Hydracept ships a Python CLI and SDK, a TypeScript SDK on npm, a .NET client on NuGet, and a Unity Editor package.
