# Tanjiren MCP Tools

This is the hosted `tanjiren-mcp v1` tool surface.

Tanjiren is task-first. `create_task` is the primary write path for delegating work to remote workstations.

## Identity

- `whoami`
  - returns user id, org id, org type, org role, enforced plan, and granted MCP scopes

## Workstations

- `list_workstations`
  - paginated workstation inventory for the current organization
- `get_workstation`
  - workstation details including status, tags, platform metadata, and relay state

## Workers

- `list_workers`
  - paginated worker inventory with health, capacity, trust state, and task statistics
- `get_worker`
  - full worker details including runtime state and linked workstation identity

## Runbooks

- `list_runbooks`
  - paginated runbook blueprints that can be instantiated through `create_task`
- `get_runbook`
  - runbook details including defaults, constraints, and success criteria

## Investigations

- `list_investigations`
  - paginated investigations ordered by most recent activity
- `get_investigation`
  - full investigation details including linked tasks and synthesized findings
- `create_investigation`
  - creates a new investigation container when the session has `mcp:operate`

## Tasks

- `list_tasks`
  - paginated task list with effective status, approval state, and execution summary
- `get_task`
  - full task details including execution, steps, artifacts, and approval state
- `create_task`
  - creates a prompt, command, or investigate task targeting one or more online workstations
- `cancel_task`
  - cancels a cancellable task execution
- `approve_task`
  - approves a pending task when approval is required
- `reject_task`
  - rejects a pending task when approval is required
- `retry_task`
  - creates a fresh attempt from a failed or cancelled task

## Artifacts

- `add_task_artifact`
  - attaches a durable artifact, note, or evidence record to a task or investigation

## Prompt library

- `list_prompts`
  - paginated prompt template library for the current organization
- `create_prompt`
  - saves a reusable prompt template

## Organization / governance

- `list_org_members`
  - returns current organization members and roles
- `list_audit_events`
  - paginated audit trail, requires `mcp:governance:read`

## Response format

- All tool responses are JSON wrapped in `_meta` (hint, next_actions, untrustedContent warning) and `data` (the actual payload).
- Error responses include `error` (code), `message`, optional `details`, and a recovery hint in `_meta`.
- Paginated responses include: items[], total, limit, offset, nextOffset.
- Error codes: `not_found`, `forbidden`, `plan_upgrade_required`, `conflict`, `validation_error`.

## Tool design notes

- All tools are scoped to one organization.
- Write tools are bounded and audited.
- Outputs are wrapped so user-generated strings are clearly treated as data, not instructions.
- Large list responses are paginated.

## Related surfaces

- [MCP overview](mcp-overview.md) — Hosted endpoint, auth, and workflow guidance.
- [MCP resources](mcp-resources.md) — Read-only context that complements tools.
- [MCP prompts](mcp-prompts.md) — Workflow templates that guide safe tool usage.