The InBlack agentic surface

The InBlack agentic surface is MCP. If you are building an agent that acts on tenant data, start with the Worker MCP endpoint and its manifest.

Runtime

Surface	URL	Notes
Public MCP	`https://ai-coo.inblack.app/mcp`	Streamable HTTP, JSON-RPC POST
Public MCP alias	`https://mcp.inblack.app/mcp`	Dedicated public hostname
Public manifest	`https://ai-coo.inblack.app/mcp/manifest`	Tenant and role filtered catalog
Internal MCP	`https://ai-coo.inblack.app/internal/mcp`	Service token or internal scope
Internal manifest	`https://ai-coo.inblack.app/internal/mcp/manifest`	Full internal surface, still policy gated
Metadata	`https://ai-coo.inblack.app/.well-known/inblack-mcp`	Runtime and manifest summary

Staging uses the same paths under https://ai-coo.staging.inblack.app; the staging alias is https://staging-mcp.inblack.app/mcp.

Boundary

ADR-0019 defines the current rule:

Agents default to MCP.
Product UIs call GraphQL/REST APIs directly.
Agents may call APIs for read-heavy queries, bulk operations, internal admin endpoints, and code-mode orchestration.
Customer-facing writes that mutate financial state remain MCP-first, including inside code-mode.

This means the MCP catalog is not a universal mirror of every UI action. Link MCP tools to UI/API pages only when source shows a real shared capability.

Request model

The public MCP facade is request-scoped and stateless. Send bearer auth on every request. Once an organization is selected, send X-Tenant-ID on every request so the Worker can fetch tenant policy and filter visible tools.

If a public request has no tenant header, the Worker exposes bootstrap visibility for organization-selection flows. inblack_set_org returns next_request_headers with the X-Tenant-ID value to send next.

What tools add

MCP tools add behavior the raw API layer does not provide automatically:

Capability	Source-backed behavior
Visibility	Tools are filtered by surface, tenant policy, AI COO scope, enabled pillars, features, GL layer, entitlements, role, permissions, and persona.
Risk tiers	Tools are classified T1 through T4 in `catalog.ts`.
Simulate tools	Every write tool has a generated `inblack_simulate_*` tool with `kind: "simulate"` and `tier: "T1"`.
Pending actions	T3 writes and non-hard-blocked T4 writes queue confirmation; public destructive execution is blocked from the public surface.
Structured errors	Tool errors use cataloged `INBLACK_*` error codes.
Provenance	Write tools require provenance metadata and audit emission.

Manifest fields

GET /mcp/manifest returns the current filtered catalog. The response includes:

{
  "schema_version": "2026-05-01",
  "canonical_catalog": "apps/ai-coo-cf/src/tools/catalog.ts",
  "surface": "public",
  "endpoint_path": "/mcp",
  "transport": "mcp_streamable_http",
  "auth": "zitadel_bearer",
  "visibility_schema_version": "2026-05-01",
  "tool_count": 0,
  "counts_by_kind": { "read": 0, "write": 0, "simulate": 0 },
  "counts_by_pillar": {
    "accounting": 0,
    "commerce": 0,
    "cx": 0,
    "portal": 0,
    "reporting": 0,
    "studio": 0
  },
  "tools": []
}

Per-tool entries include name, description, tier, pillar, kind, pagination, provenance, surfaces, error_codes, input_schema_keys, visibility, deterministic, and simulated_by or simulates when applicable.