Lets AI agents discover capabilities, submit durable jobs, and retrieve artifacts and receipts through one hosted execution API.
Also known as zencodeinc/hydracept-public, hydracept-public
- Stars
- 0
- Tools
- 45
- Downloads, 30 days
- 645
- Latest version
- 0.5.7
- Last commit
- Nov 12, 2026
- License
- MIT
What is Hydracept MCP?
Hydracept lets AI agents discover capabilities, submit durable jobs, and retrieve artifacts and receipts through one hosted execution API. It exposes 45 tools, such as hydracept_capabilities, hydracept_quote_capability, hydracept_invoke.
Summary generated from the project's README
About Hydracept MCP server
Providing external capabilities like image generation, reasoning, and compute to AI agents is what Hydracept enables through a single execution control plane. Developers using Cursor, Claude Code, or Unity can connect their workflows to a wide range of services including text, audio, video, and 3D assets. The system supports both local stdio MCP setups via a Python CLI and remote hosted MCP connections using an API key.
Users manage these tasks through a unified API that handles capability discovery, durable job submission, and the retrieval of artifacts and receipts. The platform offers flexible billing options, including a Bring Your Own Key model with no service fee and managed inference with a 6% service fee. For long-running text tasks, deferred processing is available at half the standard token rate. Integration is straightforward using the Python, TypeScript, or .NET SDKs, or by installing the Unity package via UPM git.
What you can do with it
- 1Generate game assetsAn AI agent can create specific visual assets like icons directly for use in a game engine.
Written from the project's README. Every use case is checked against a quote from it.
How to install Hydracept MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Hydracept MCP in Claude Code
$ claude mcp add --env 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' hydracept-public -- uvx hydracept mcp serveInstall Hydracept MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hydracept-public": {
"command": "uvx",
"args": [
"hydracept",
"mcp",
"serve"
],
"env": {
"HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
}
}
}
}Install Hydracept MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hydracept-public": {
"type": "stdio",
"command": "uvx",
"args": [
"hydracept",
"mcp",
"serve"
],
"env": {
"HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
}
}
}
}Install Hydracept MCP in VS Code CLI
$ code --add-mcp '{"name":"hydracept-public","type":"stdio","command":"uvx","args":["hydracept","mcp","serve"],"env":{"HYDRACEPT_API_KEY":"<YOUR_HYDRACEPT_API_KEY>"}}'Install Hydracept MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hydracept-public": {
"command": "uvx",
"args": [
"hydracept",
"mcp",
"serve"
],
"env": {
"HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
}
}
}
}Install Hydracept MCP in Codex
$ codex mcp add hydracept-public --env 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' -- uvx hydracept mcp serveInstall Hydracept MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hydracept-public] command = "uvx" args = ["hydracept", "mcp", "serve"] [mcp_servers.hydracept-public.env] HYDRACEPT_API_KEY = "<YOUR_HYDRACEPT_API_KEY>"
Install Hydracept MCP in Gemini CLI
$ gemini mcp add -s user -e 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' hydracept-public uvx -- hydracept mcp serveInstall Hydracept MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hydracept-public": {
"command": "uvx",
"args": [
"hydracept",
"mcp",
"serve"
],
"env": {
"HYDRACEPT_API_KEY": "<YOUR_HYDRACEPT_API_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for hydracept 0.5.6 in an isolated container with no network and no keys. It answered and listed 45 tools.
Hydracept MCP tools 45
Read from the server with tools/listhydracept_capabilitiesBrowse 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_capabilityPreview 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_invokePOST /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_jobRequest 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_receiptRead 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_artifactFetch 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_smokeRuns 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_runPOST /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_bulkPOST /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_getGET /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_getGET /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_createPOST /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.
Show all 45 toolsShow fewer tools
hydracept_manifest_verifyPOST /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_emitGET /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_lockfilePOST /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_findFind 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_inspectRead 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_statusRead login-persistent project up status from local checkout (stdio, cwd=project). Side effects: none.
hydracept_project_up_installRun project up --install locally (stdio). Side effects: local install argv.
hydracept_surface_applyApply surface JSON to project checkout (stdio). Does not grant allowlist by itself.
hydracept_project_syncSync operations allowlist from tools/hydracept/manifest.json (stdio). Side effects: rewrites allowlist file.
hydracept_project_watch_onceExecute pending project operations once (stdio). Side effects: local argv execution.
hydracept_project_request_operationPOST /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_operationGET /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_jobPanel submit job; same execution as hydracept_submit_job.
hydracept_ui_poll_jobPanel poll job once; same API projection as hydracept_job_status.
hydracept_ui_download_artifactPanel save artifact into workspace (stdio App).
hydracept_ui_artifact_previewPanel bounded artifact preview (stdio App). Read-only media preview.
hydracept_ui_quotePanel quote adapter; same primitive as hydracept_quote_capability.
hydracept_ui_runPanel run adapter choosing invoke vs jobs from descriptor executionModes.
hydracept_ui_connect_projectPanel init/connect flow (stdio App). Does not replace python -m hydracept init binding writes.
hydracept_ui_connection_recheckPanel read-only connection/runnability recheck. No secret arguments.
hydracept_ui_approve_jobPanel POST /v1/jobs/{id}/approve (stdio App). Same API as human approval gate.
hydracept_ui_reject_jobPanel POST /v1/jobs/{id}/reject.
hydracept_ui_select_variantPanel POST /v1/jobs/{id}/variants/select.
hydracept_ui_cancel_jobPanel POST /v1/jobs/{id}/cancel. Side effects: cancels job when policy allows.
hydracept_ui_promotePanel apply_surfaces(path) locally; cloud never writes git checkout.
hydracept_runRun 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_jobStart 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_statusRead 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_surfacePresent Hydracept App UI resource (stdio). Use when init/onboarding returns present_and_yield. Auth: workspace session. Side effects: UI presentation only.
resolve_capabilityMatch 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_quotePOST /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_quoteGET /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_statusCheck 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.
Configuration
HYDRACEPT_API_KEYRequiredSecretHydracept 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_PROFILEStdio 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.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablezencodeinc/hydracept-public is public and reachablegithub.com/zencodeinc/hydracept-public ↗Pass
- Package names this repository as its sourcehydracept names zencodeinc/hydracept-public as sourcepypi.org/project/hydracept/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for hydraceptpypi.org/project/hydracept/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/zencodeinc/hydracept-public ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from hydraceptPass
- No critical advisory in the package or its dependenciesthe package checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model45 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubHydracept
Hydracept is an execution control plane for software and AI agents that need external capabilities—text, reasoning, image, audio, video, 3D, domains, and compute—through one API with discovery, quotes, durable jobs, artifacts, receipts, budgets, and BYOK. Games and media are common examples; a headline workflow is AI game assets from Cursor or Claude Code into Unity (workflow overview).
Pricing (summary): Free plan ($0/mo) for individuals; paid plans add capacity. BYOK at 0% Hydracept fee; managed inference is provider cost + 6% service fee (actual usage, no per-call minimum). Eligible durable text jobs can use deferred processing at 50% of standard token rates. Details: hydracept.com/pricing and Billing docs.
Install
| Surface | Command |
|---|---|
| Python CLI & SDK | pip install -U hydracept |
| TypeScript | npm install @hydracept/sdk |
| .NET | dotnet add package Hydracept.Client |
| Unity (UPM git) | com.hydracept.unity via Git URL — see Unity integration (OpenUPM listing pending owner submit) |
Public HTTP API: https://api.hydracept.com · OpenAPI: hydracept-v1.json · Agent context: GET https://api.hydracept.com/v1/agent-context
Bootstrap
pip install -U hydracept
python -m hydracept init --apply --yes --json
python -m hydracept doctor
Studio (browser): app.hydracept.com/login. For CI or headless use, set HYDRACEPT_API_KEY and run the same init command with --ci when you need setup grants. Workspace files live under .hydracept/ — see Authentication.
Minimal example
One-shot image generation (composes init when the workspace can be bootstrapped):
python -m hydracept run image.generate.v1 --prompt "transparent 1024x1024 blue slime icon" --json
Python SDK (after init binds the workspace):
from hydracept.client import HydraceptClient
client = HydraceptClient.from_workspace()
job = client.submit_capability_job(
"image.generate.v1",
{
"input": {"prompt": "cute slime icon, flat game art"},
"execution": {"executionPreference": "automatic"},
"idempotencyKey": "demo-1",
},
)
finished = client.wait_for_job(job["jobId"])
receipt = client.get_job_receipt(job["jobId"])
Discover capabilities live (do not hard-code keys from this README):
python -m hydracept capabilities find "generate an image"
curl -sS -H "Authorization: Bearer $HYDRACEPT_API_KEY" https://api.hydracept.com/v1/capabilities
More examples: public/examples/.
MCP (Cursor & Claude Code)
In a project checkout, stdio MCP is the default after init:
python -m hydracept init --apply --yes --json # binds MCP to workspace secrets; reload MCP if prompted
python -m hydracept mcp serve # stdio server
python -m hydracept agents install --auto # Cursor / Claude Code plugin + hooks
- Plugin & install links: hydracept.com/plugin
- Hosted MCP (no repo checkout):
https://api.hydracept.com/mcpwith bearerHYDRACEPT_API_KEY - MCP Registry name:
com.hydracept/hydracept
Do not paste workspace API keys into IDE plugin config when stdio bind is available. Full agent guide: Coding Agents.
Documentation
| Topic | Link |
|---|---|
| Docs home | docs.hydracept.com |
| Quick start (detailed) | Quick Start |
| Capabilities & jobs | Capabilities, Jobs & receipts |
| Image production | Image production |
| Unity | Unity integration |
| BYOK & billing | Connections / BYOK, Billing |
| LLM-oriented summary | hydracept.com/llms.txt |
| Product manifest | /.well-known/hydracept.json |
Repository layout
clients/python— PyPI packagehydracept(CLI, SDK, local MCP)clients/typescript— npm@hydracept/sdkclients/csharp— NuGetHydracept.Clientpackages/unity— Unity Editor packagepublic/docs— source for docs.hydracept.com (Quick Start content; this root README is the GitHub front door)
License
MIT — see LICENSE. Package metadata on PyPI, npm, and NuGet also lists MIT.
Hydracept MCP questions
How do I add Hydracept MCP to Claude Code?
Run claude mcp add --env 'HYDRACEPT_API_KEY=<YOUR_HYDRACEPT_API_KEY>' hydracept-public -- uvx hydracept mcp serve in your terminal. Add --scope user to make it available in every project.
How do I add Hydracept MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Hydracept MCP provide?
It exposes 45 tools, including hydracept_capabilities, hydracept_quote_capability, hydracept_invoke, hydracept_cancel_job, hydracept_get_receipt.
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.