Puras MCP Tools

The MCP is hosted — one command, OAuth, no install:

bash

claude mcp add --transport http puras https://mcp.puras.co/mcp

The first call opens a browser for Google login + consent; Claude Code stores the OAuth token and your workspace is resolved from it. There is no API key and no config file to manage. Skillpack-scoped tools take the skillpack id explicitly. Anything you can do here you can also do over the HTTP API directly — the MCP is purely a convenience for AI coding agents.

Skillpacks

list_skillpacks() -> list[dict] — List every skillpack in the workspace this token belongs to.
get_skillpack(skillpack) -> dict — Inspect one skillpack (active deployment, public flag, fork source).
create_skillpack(name, slug, description='') -> dict — Create a new private skillpack (a deployable bundle of <skill>/skill.yaml skills). Publishing to the public marketplace is a separate admin step.
update_skillpack(skillpack, name='', description='') -> dict — Rename a skillpack or change its description. Pass at least one of name/description. (Marketplace visibility is admin-only and not settable here.)
delete_skillpack(skillpack) -> dict — Delete a skillpack and all its deployments. Irreversible.
fork_skillpack(source_skillpack, name='', slug='') -> dict — Copy a public (or your own) skillpack into your workspace as a new private skillpack — a starting point you can edit and push. Copies the source's active deployment as v1; secrets and drive are NOT copied.
list_public_skills(query='', limit=60) -> dict — Browse the public marketplace — every skill in every public skillpack's active deployment. Each row carries the skillpack_id to pass to describe_skill/submit_job (run it) or fork_skillpack/pull_skillpack (start from it). To also include your OWN workspace skills in one search, use search_skills instead.

Deployments

A deployment is a whole skillpack bundle, versioned per skillpack (v1, v2, …). New deploys never overwrite old ones — activating a new version is a rolling switch, and in-flight jobs keep running on the version they were submitted against. Callers can also pin a specific version at submit time (see submit_job).

push_skillpack(skillpack, skillpack_dir, notes='', activate=True) -> dict — Push a local skillpack directory as a new deployment — in ONE command. Returns a single shell push_cmd that zips the directory, uploads it to a pre-signed URL, and finalizes the deployment (authorized by a short-lived signed ticket). The server can't read your disk, so YOU (the local agent) run push_cmd; its final output is the finalize JSON confirming the new version.
pull_skillpack(skillpack, deployment_id='', dest_dir='') -> dict — Download a deployment's bundle to edit locally and push back (clone → edit → push). Works for your OWN skillpacks (any version) and for PUBLIC skillpacks (active version only). Returns a download URL + the exact curl+unzip command for the local agent to run.
list_deployments(skillpack) -> list[dict] — List deployments for a skillpack, newest first.
activate_deployment(skillpack, deployment_id) -> dict — Make a specific deployment the active one (rolling switch / rollback).
delete_deployment(skillpack, deployment_id) -> dict — Delete a deployment. The currently-active one cannot be deleted.

Jobs

submit_job(skill, skillpack, inputs={}, version=0, wait=False, timeout=30) -> dict — Submit a job against skill in the skillpack, optionally pinned to a specific deployment version.
get_job(job_id) -> dict — Fetch current status and result of a job.
list_jobs(status='', skill='', skillpack='', limit=25) -> list[dict] — List recent jobs across the workspace, newest first.
cancel_job(job_id) -> dict — Mark a job as cancelled (the worker checks between agent steps).
tail_job(job_id, max_seconds=60) -> dict — Poll job events until the job terminates or max_seconds elapses. Returns the collected events plus the final job row.

Secrets

Values are write-only — the API never returns them.

list_secrets(skillpack) -> list[dict] — List secret names for a skillpack. Values are NEVER returned.
set_secret(skillpack, name, value) -> dict — Create or overwrite a skillpack secret (env-var-style name ^[A-Z_][A-Z0-9_]*$). Injected as an env var into the agent's bash tool + skill subprocess at run time.
delete_secret(skillpack, name) -> dict — Delete a skillpack secret.

Account

whoami() -> dict — Return the current workspace identity — id, email, workspace name/slug, and credit balance. Use the slug to build /skills/<workspace_slug>/... links.
get_balance() -> dict — Return the workspace's credit balance + month/day spend. Check before running paid jobs.

Drive

The workspace drive is the shared file store skills read inputs from and write outputs to.

drive_sign(path, ttl=3600) -> dict — Return a signed URL for a file under the workspace drive (path relative to the workspace drive root, e.g. "uploads/logo.png").
drive_list(prefix='', sign=False, limit=200) -> dict — List files + folders under a drive prefix (e.g. "variants/"). Empty prefix = workspace root. Set sign=True to also get signed URLs for each file. Use this to discover job output files.
drive_upload_url(path='', filename='', content_type='') -> dict — Mint a one-time signed URL to upload an INPUT file straight to the workspace drive (e.g. a logo/video/csv to feed into a job). Returns upload_url (PUT the bytes) + drive_path (pass as a job input). The local agent uploads with: curl -X PUT --data-binary @<file> '<upload_url>'.

Other

describe_skill(skillpack, skill) -> dict — Inspect one skill so you know how to call it: returns its description, input_schema/output_schema, examples, run mode and media defaults, plus the skillpack_id+skill to pass straight to submit_job. Works for your own skillpacks and any public one (active deployment).
describe_skillpack(skillpack) -> dict — Describe a whole skillpack at once — its name/description and EVERY callable skill (with input/output schemas + examples) — so you can plan a multi-skill workflow and chain submit_job calls. Works for your own skillpacks and any public one (active deployment).
get_hindsight(run_id) -> dict — Read one Hindsight report: status, the window analyzed, and the findings (severity-ordered) — each with its evidence, recommendation, and optional draft (a proposed tool spec / SKILL.md patch / memory action).
list_hindsight(skillpack, skill='', limit=20) -> list[dict] — List recent Hindsight retrospectives for a skillpack, newest first. Filter to one skill to search its history.
run_hindsight(skillpack, skill) -> dict — Trigger a Hindsight retrospective: analyze a skill's recent runs for recurring inefficiencies (ad-hoc code that should be a tool, repeated errors, redundant calls, memory misuse) and propose fixes. Returns the run row; the analysis runs in the background — poll get_hindsight(run_id) for findings. Report only — nothing is applied automatically.
search_skills(query='', scope='all', limit=60) -> list[dict] — Discover skills you can RUN — across the public marketplace AND your own workspace — then run them with submit_job. The unified "what can Puras do?" entry point: every result carries skillpack_id + skill (and a scope of "public"/"workspace") to pass to describe_skill (learn its inputs) and submit_job (run it).
submit_feedback(job_id, rating=0, comment='', end_user_id='') -> dict — Record a thumb and/or a comment on a job's result, so you can later see which skills run well and which don't.

Conventions an AI agent should follow

Prefer from puras import media inside skill code over raw HTTP to /v1/media/generate — same backend, but the SDK handles auth, drive paths, and billing context for you. See sdk-runtime-reference.
Don't push partial bundles; a deployment is the whole skillpack. If you want to ship one fix, that's still a new full deployment.
Don't assume wait=true returns terminal state. Long jobs need tail_job or repeated get_job.
Pin a version on submit_job when you depend on a release you've validated — the active deployment moves forward as new versions ship.