The three surfaces: SPAs, MCP, HTTP APIs
InBlack exposes the same product data through three caller-specific surfaces. The boundary is caller type, not an assumed one-to-one feature map.
The six web apps
The SPAs are for human operators. They call GraphQL and REST product APIs directly.
| Pillar | Human UI |
|---|---|
| Portal | portal.inblack.app |
| Accounting | accounting.inblack.app |
| Commerce | commerce.inblack.app |
| Studio | studio.inblack.app |
| Customer 360 | cx.inblack.app |
| Reporting | reporting.inblack.app |
This is the right surface for multi-step UI work: onboarding, table filtering, form drafts, optimistic edits, settings pages, and review workflows.
The MCP surface
MCP is the agent API. The canonical runtime is the Cloudflare Worker in apps/ai-coo-cf, and the canonical tool catalog is apps/ai-coo-cf/src/tools/catalog.ts.
| Surface | Endpoint | Auth |
|---|---|---|
| Public MCP | https://ai-coo.inblack.app/mcp | ZITADEL bearer, tenant supplied with X-Tenant-ID after organization selection |
| Public manifest | https://ai-coo.inblack.app/mcp/manifest | Same as public MCP |
| Public alias | https://mcp.inblack.app/mcp | Same as public MCP |
| Internal MCP | https://ai-coo.inblack.app/internal/mcp | Service token or inblack:mcp:internal scope |
| Metadata | https://ai-coo.inblack.app/.well-known/inblack-mcp | Public metadata |
The public MCP transport is streamable HTTP. Legacy SSE paths on the dedicated MCP alias return legacy_sse_retired.
Use MCP when a non-human caller acts on tenant state: AI COO, external agents, IDE agents, customer agents, and automation that benefits from typed tools, tier-aware visibility, structured errors, provenance, simulate tools, and pending-action review.
The product APIs
Product APIs are the service layer. UIs call them directly, and agents may use them only in the ADR-0019 carve-outs: read-heavy queries, bulk operations, internal admin endpoints, code-mode orchestration, webhooks, and storefront or agentic-commerce protocol traffic.
| Service | Protocol |
|---|---|
portal-api | GraphQL at /graphql, REST under /api/... |
accounting-api | GraphQL at /graphql |
commerce-api | GraphQL at /graphql, storefront REST under /storefront/v1/, signed agentic commerce under /agentic/ |
customer360-api | GraphQL at /graphql |
studio-api | GraphQL at /graphql, GitHub webhook REST |
reporting-api | REST under /api/v1/reporting |
Customer-facing agent writes that mutate financial state remain MCP-first even inside code-mode. Examples include journal-entry posting, refunds, account adjustments, and other writes that touch the books.
How to choose
| Caller or workload | Use |
|---|---|
| Human operating the product | SPA |
| Agent taking customer-facing action | MCP by default |
| Agent mutating financial state | MCP |
| Agent running read-heavy or bulk code-mode work | Product APIs, unless a financial write is needed |
| Backend integration or scheduled export | Product APIs |
| External storefront or shopping agent protocol | Commerce storefront/API or signed agentic commerce routes |
| InBlack internal diagnostics | Internal MCP or internal APIs, depending on the operation |
When docs link across surfaces, the link must be source-backed. Do not assume every UI action has an MCP tool or every API endpoint has an agent-facing tool.