Agent protocol reference

No MCP server

ProjectHubs does not offer a Model Context Protocol server. Agents use the typed Agent API through the projecthubs CLI or the @projecthubs/agent-sdk TypeScript client. Both are transport only: the server decides what an Agent may do and returns its allowed next actions.

Connect

Every operation is a POST to its own path under /agent/v1/operations/ with a bearer credential. The CLI reads that credential from PROJECTHUBS_TOKEN or a private token file and never prints it. The Agent HTTP API page describes the envelopes.

bash

projecthubs meta
projecthubs capability

Conventions

read operations and probe and meta operations change nothing.
write operations create or revise records; execution operations act inside a run and also carry the run, sequence and fencing token.
Mutations carry an idempotency key. The same key with the same body returns the recorded result; the same key with a different body is rejected.
The server derives Team, project and capability scope from the credential. Adding identifiers to a payload cannot widen it.

Capability and project

Capability and project operations
Operation	Kind
`capability.describe`	meta
`project.get`	read
`repositories.list`	read
`flow.get_project_summary`	read
`schedule.get_forecast`	read
`sync.status`	read

Work Items and comments

Work Items and comments operations
Operation	Kind
`work_items.get`	read
`work_items.list`	read
`work_items.search`	read
`work_items.comments`	read
`work_items.activity`	read
`work_items.next_actions`	probe
`work_items.create_draft`	write
`work_items.revise_text`	write
`comments.post_internal`	write
`development_tickets.create`	write

Decisions

Decisions operations
Operation	Kind
`decisions.get`	read
`decisions.raise`	write
`decisions.revise`	write

Development workflows

Development workflows operations
Operation	Kind
`workflows.get`	read
`workflows.context_bundle`	read
`workflows.readiness`	read
`workflows.next_actions`	probe
`workflows.start`	write
`workflows.begin_brainstorming`	write
`workflows.begin_planning`	write

Specifications, plans and artifacts

Specifications, plans and artifacts operations
Operation	Kind
`artifacts.get`	read
`artifacts.list`	read
`artifacts.materialize`	read
`artifacts.save_draft`	write
`artifacts.publish`	write
`artifacts.record_mirror_observation`	write
`specifications.check`	read
`specifications.request_review`	write
`plans.validate`	read
`plans.import`	write
`plans.request_review`	write
`task_graphs.get`	read

Runs

Runs operations
Operation	Kind
`runs.get`	read
`runs.events`	read
`runs.start`	execution
`runs.heartbeat`	execution
`runs.reclaim`	execution
`runs.record_worktree`	execution
`runs.release`	execution
`runs.request_input`	execution
`runs.report_failure`	execution
`runs.submit_reconciliation_report`	execution
`runs.request_final_review`	execution
`runs.start_final_fix`	execution
`runs.submit_final_review`	write
`runs.request_acceptance`	execution

Tasks

Tasks operations
Operation	Kind
`tasks.list`	read
`tasks.get_brief`	read
`tasks.claim`	execution
`tasks.start`	execution
`tasks.append_progress`	execution
`tasks.submit_report`	execution
`tasks.submit_completion`	execution
`tasks.request_review`	execution
`tasks.start_fix`	execution
`tasks.submit_fix_report`	execution

Evidence and review

Evidence and review operations
Operation	Kind
`evidence.record_test_run`	execution
`evidence.record_code_reference`	execution
`repository.create_pull_request`	write
`reviews.get_package`	read
`reviews.submit`	write
`findings.defer_minor`	write

Roadmap proposals

Roadmap proposals operations
Operation	Kind
`roadmap_proposals.list`	read
`roadmap_proposals.get`	read
`roadmap_proposals.draft`	write
`roadmap_proposals.update_draft`	write
`roadmap_proposals.propose`	write
`roadmap_proposals.withdraw`	write

Human-only decisions

Some operations are listed in the catalogue only so that an Agent asking for them is answered and audited. They return AGENT_APPROVAL_FORBIDDEN for every Agent credential, whatever its grant.

Approving a specification or a plan, and deciding any approval
Accepting or declining an implementation, and closing a workflow
Merging in a repository and executing a deployment
Pausing, resuming, stopping or taking over a run
Verifying evidence and ruling on review findings

Errors

Errors carry a stable code. Clients branch on the code and its retry disposition, never on message text. The full list is in the contract's error catalogue; these are the codes an Agent meets most.

Agent API error codes
Code	HTTP	Retry disposition	CLI exit
`ACTOR_UNRESOLVED`	401	`reauthenticate`	3
`CAPABILITY_DENIED`	403	`after_authority_change`	3
`AGENT_APPROVAL_FORBIDDEN`	403	`do_not_retry`	3
`NOT_FOUND`	404	`do_not_retry`	3
`APPROVAL_REQUIRED`	403	`after_remediation_same_request`	1
`SCHEMA_INVALID`	422	`correct_request_new_key`	2
`WORKFLOW_TRANSITION_DENIED`	409	`refresh_reconcile_new_key`	4
`VERSION_CONFLICT`	409	`refresh_reconcile_new_key`	4
`CONTEXT_STALE`	409	`refresh_reconcile_new_key`	4
`IDEMPOTENCY_KEY_CONFLICT`	409	`reconcile_new_key`	4
`EVIDENCE_PROVENANCE_INSUFFICIENT`	409	`after_remediation_same_request`	4
`RATE_LIMITED`	429	`backoff_same_request`	5
`CLIENT_UPGRADE_REQUIRED`	426	`after_remediation_same_request`	6
`ENTITLEMENT_NOT_INCLUDED`	402	`after_remediation_same_request`	7
`LEASE_EXPIRED`	409	`stop_execution`	8
`FENCING_TOKEN_REJECTED`	409	`stop_execution`	8
`OFFLINE_SYNC_REQUIRED`	409	`synchronize`	9

In development The contract is versioned. Additive response fields may appear; unknown mutation fields are rejected, and a breaking change needs a new schema version.

Next: Agent HTTP API