How BotDigit MCP Works
BotDigit MCP operates as a hardened, capability-scoped execution layer between large language models and BotDigit’s backend Work OS. It enforces workspace sandboxing, strict token authorization, and human-in-the-loop gates without exposing underlying database internals.
High-Level System Architecture
Rather than granting AI agents raw database credentials or unrestricted shell access, BotDigit exposes a typed JSON-RPC interface that translates natural language intentions into verified business actions.
Dual Transport: Stdio vs. SSE
The MCP specification provides two primary transport mechanisms. BotDigit natively supports both depending on whether your AI agent runs locally on your workstation or in the cloud:
Local IDE Execution
Designed for developer tools running on your machine like Cursor, Claude Desktop, and VS Code. The IDE launches our lightweight Node.js CLI process as a child process, communicating over standard input and output streams.
- Zero open network ports required locally
- Environment variable configuration (
BOTDIGIT_API_TOKEN) - Sub-millisecond local process dispatch
npx -y @botdigit/mcp-serverRemote & Cloud Agents
Designed for cloud-hosted AI agents, web-based ChatGPT Custom Actions, and autonomous server-side orchestrators. Communicates via HTTP POST for requests and persistent Server-Sent Events (SSE) streams for responses.
- Standard HTTPS over TLS 1.3 encryption
- Bearer token header authentication
- Supports server-initiated notification pushes
https://botdigit.com/api/v1/mcp/sseThe 6-Step MCP Request Lifecycle
Every tool execution passes through rigorous validation stages before altering any platform state:
Client Capability Discovery
Upon connection, the client issues tools/list. BotDigit responds with schemas strictly tailored to the authenticated token’s granted scopes (e.g., read vs. write).
Prompt & Parameter Construction
The LLM decodes user intent and structures tool arguments adhering to JSON Schema constraints defined in the tool definition.
Gateway Authentication & Scoping
The BotDigit MCP Gateway validates the PAT, inspects workspace membership, and blocks unauthorized cross-tenant data access.
Safety Interception & Staged Actions
If the operation modifies funds (e.g. prepare_payment_release), the gateway stages the action, generates an approval token, and returns a secure review link.
Execution & Evidence Logging
Permitted operations execute through Platform Core. An immutable event entry is recorded to the BotDigit Evidence Ledger.
Structured JSON-RPC Response
The gateway packages results into a standardized JSON-RPC 2.0 response and streams it back to the client context.
Strict Application Boundary: No Direct Database Access
A common vulnerability in naive agent implementations is connecting models directly to SQL databases. In BotDigit, the MCP Server has zero database connection strings and zero raw SQL capabilities.
All read and write operations route through the compiled Rust Platform Core service via internal API contracts. This guarantees that row-level security, business invariants, escrow constraints, and multi-tenant isolation remain completely inviolable.
Explore Available Tools
Inspect all 17 MCP tools available to agents.