MCP reference
The Nebbos MCP surface exposes 13 core tools organised into seven capability categories. The MCP classifier assigns each tool call to the appropriate data tier on the operator’s host. The substrate evaluates every request against operator identity, tier, and policy before executing.
Tool discovery
Integrations should pin against list_available_tools rather than a hard-coded roster. The MCP surface is self-describing: the discovery tool returns each current tool with its input schema, output shape, and required operator tier. Additions to the tool set become available to an integration on its next discovery pass.
Capability categories
| Category | Tool count | Tier requirement | Purpose |
|---|---|---|---|
| Pearl query | 2 | Guest | Natural-language queries against a department-scoped Pearl |
| Signals and risk | 2 | Host (for acknowledgement) | Cross-domain risk signals produced by the Orchestrator; acknowledgement requires the human-token attribution tuple |
| Project and task operations | 13 | Guest (read), Host (write) | Read and write the operational-work tracker. Writes require justification and verification fields. |
| Departments and workspace | 6 | Guest (read), Architect (create) | The organisational structure within which Pearls operate |
| Audit chain | 3 | Host | Read the hash-chained audit log; walk a chain segment and receive a signed verification receipt |
| Context and knowledge | 5 | Guest | Knowledge graph, memory registers, playbook catalog, predictions |
| Discovery | 1 | Guest | Self-describing entry point; returns the live tool roster with input schemas and tier requirements |
Representative tools by category
- Pearl query:
query_pearl,describe_pearl - Signals and risk:
get_active_signals,acknowledge_signal - Project and task operations:
list_projects,get_project,create_project,list_tasks,get_task,create_task,assign_task,update_task_status,update_tasks_bulk - Departments and workspace:
list_departments,create_department,compare_departments,list_workspace_users - Audit chain:
audit_event_list,audit_event_get,audit_event_hash_chain_verify - Context and knowledge:
get_context,get_knowledge_graph,analyze_gaps,search_insights,search_playbook_catalog,get_predictions - Discovery:
list_available_tools
Authentication requirements
Every MCP request carries a Bearer token. Every write additionally carries a delegation token identifying the human on whose authority the call is made. Bearer tokens expire fifteen minutes after issuance.
See Authentication & tiers for the mapping of Guest, Host, and Architect tiers to integration identity requirements.
Human-in-the-loop authorisation
Tools that accept a human_token input require a signed approval from the verified human delegator on the same request. The substrate refuses the call if the token cannot be verified, has expired, or if the delegator’s scope does not cover the operation. Delegation tokens are issued through the human-approval flow and passed into subsequent tool calls.
Audit-chain recording
Every MCP invocation produces one entry in the hash-chained audit log, including tool name, input hash, output hash, tier, delegator, timestamp, and the chain hash. No MCP operation is exempt from chain recording. See The audit chain.