Companies - PlungeAI

Source: orchestration/mcp-gateway/tools-companies.ts (CompaniesSchema, plungeaiCompanies), orchestration/mcp-gateway/ops/companies.ts (decideGate), orchestration/mcp-gateway/shared.ts (refusalResult, valueResult), orchestration/company-service/contract.ts (CompanyServiceApi, the request and response types), orchestration/api-gateway/routes/companies.ts (the REST twin).

A company is a campus compiled from documents you saved as workflows: one kind: campus document, its kind: building documents and their offices. plungeai_companies is the MCP door to it, action for action the One API's /v1/companies: the same company-service, called as you, with the same bodies and the same refusals. Full parameter table: 14.21.

16.1 Tenancy

The key's user is the tenant. Every action but list takes campus (the slug of a campus you saved), and company-service only finds campuses you own: a campus another account owns is the same not_found as one that does not exist, so the answer never tells you that a slug is taken. A slug that cannot be a campus slug (lowercase letters, digits and dashes, 1–63 characters) is not_found without a call.

16.2 Actions

`action`	Needs	REST twin	Does
`list`	nothing	`GET /v1/companies`	your campuses: slug, name, mode, status, buildings, pending gates
`apply`	`campus`	`POST /v1/companies/{campus}/apply`	compiles the saved documents and stores the plan; idempotent by name
`layout`	`campus`	`GET …/layout`	the compiled campus, buildings and offices
`snapshot`	`campus`	`GET …/snapshot`	live state: offices, items, the queue of pending gates, spend today
`events`	`campus`; optional `since` (default 0), `limit` (default 200, max 1,000)	`GET …/events` (JSON page)	the event log after `since`, oldest first. The server-sent stream is REST only
`ingest`	`campus`, `events` (1–200)	`POST …/events`	a local building reports its events up
`slice`	`campus`, `building`	`GET …/buildings/{building}/slice`	the part of the plan one building runs
`item_create`	`campus`, `building`, `title`; optional `body`, `kind`, `priority`, `tier`	`POST …/items`	puts an item through the building
`item_pause`, `item_resume`, `item_retry`, `item_cancel`	`campus`, `item_id`	`POST …/items/{id}/{verb}`	moves one item
`item_steer`	`campus`, `item_id`, `text`	`POST …/items/{id}/steer`	a message for the item's running office
`approvals`	`campus`; optional `status`	`GET …/approvals`	the gates at the door
`decide`	`campus`, `approval_id`, `decision`; optional `note`	`POST …/approvals/{ap}`	records the decision; see 16.3
`mode`	`campus`, `mode`	`PUT …/mode`	`supervised`, `tiered` or `autonomous`: who decides the gates
`start`, `stop`	`campus`	`POST …/start`, `POST …/stop`	arms or stops the campus clock
`delete`	`campus`	`DELETE /v1/companies/{campus}`	deletes the campus and every row of it; the saved documents stay, so it can be applied again

16.3 Deciding a gate

Only send decide after the user decided. For a tool_permission gate, approve continues the execution that paused for it, once, as you, and hands the result back to the company so the item moves on: the answer carries execution_id and continued: true. A continue that cannot run is reported beside the recorded decision (continued: false with continue_error: not_paused, session_expired, execution_not_found or continue_failed), never raised. reject leaves the run paused: nothing is continued.

16.4 Answers and refusals

An answer is a heading line (for example Created item `<id>` on `<campus>`.) and the REST response body as a JSON block; the same body is structuredContent. A refusal is isError: true text <word>: <message> (<code>), and structuredContent.error is {status, code, message}:

`status` word	REST status	Typical codes
`invalid`	400, 422	`invalid_params` (a missing or malformed argument; no call is made)
`not_found`	404	`company_not_found`, `building_not_found`, `item_not_found`, `approval_not_found`
`conflict`	409	`conflict` (`delete` while the campus runs — stop it first), `item_done`, `approval_not_pending`
`unavailable`	5xx	`not_enabled` (no company service on this deployment), `upstream_error` (the call failed; retry)

Try asking:

"Which companies do I have?" → list
"Add an item to the docs building: write the onboarding guide." → item_create
"What is waiting for my approval at plunge?" → approvals, then decide once the user says so
"Shut plunge down and delete it." → stop, then delete

List your companies (read-only):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_companies","arguments":{"user_request":"which companies do I have?","action":"list"}}}'

Put an item through a building. This changes state (not verified here):

curl -s https://mcp.plungeai.com/v1 \
  -H "Authorization: Bearer $PLUNGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"plungeai_companies","arguments":{"user_request":"have the docs building write the onboarding guide","action":"item_create","campus":"<campus slug>","building":"<building slug>","title":"Write the onboarding guide","kind":"docs"}}}'