Licensed to be used in conjunction with basebox, only.
// integration
Architecture
Applies to
Product: Cloud · Server · Audience: Developer / Integrator · Platform Operator
How a connector sits between basebox and an external system: MCP gateway, egress allowlist, enablement per app, and where credentials live. Knowing these boundaries makes you build the server so that it can be operated securely by default.
The picture
flowchart LR
subgraph BB["basebox environment"]
AISRV["AISRV<br/>MCP gateway · access control · per-user credentials"]
DB[("basebox DB<br/>per-user settings<br/>per-app tool enablement")]
MCP["Your MCP server<br/>container · service mcp-<name><br/>HTTP /mcp"]
AISRV --- DB
AISRV -->|"POST /mcp<br/>Authorization: <user token>"| MCP
end
MCP -->|"only this host<br/>(egress allowlist)"| EXT["Target system<br/>wiki · tickets · business app"]
MCP -. "blocked" .-x OTHER["everything else"]
style AISRV fill:#f4f2ee,stroke:#524e47,color:#1d1e1c
style MCP fill:#dcefe2,stroke:#3a7a49,color:#1d1e1c
style EXT fill:#dbeafe,stroke:#1e40af,color:#1d1e1cThe building blocks
AISRV (MCP gateway). Validates the user token, loads from the basebox database this user's credentials for your connector and the tool enablement of the current app, forms the intersection, offers the permitted tools to the model, intercepts calls, sets the Authorization header and calls your server. It frames your result as data and records the call in the audit log.
Your MCP server. A container in the basebox cluster (on Server via Helm as a byo connector; service mcp-<name>, endpoint http://mcp-<name>:<port>/mcp) or – where available – an MCP endpoint hosted by the vendor. It translates tool calls into API calls of the target system and responses into bounded, structured results.
The target system. Enforces its own permissions because it receives the request with the person's credentials.
Where credentials live
| Kind | Location | Who sees them |
|---|---|---|
| Personal credentials (token per user) | basebox database, user settings table; write-only, never returned to the browser, hidden in logs | Nobody – not even an administrator; your server receives them per request in the header |
| Machine credentials (service account, connector API key) | Kubernetes secret, via valueFrom.secretKeyRef as environment variable into your container |
Platform Operator |
| Configuration (base URL, endpoints) | Helm values (global.<system>.…) or admin interface |
Platform Operator, administrator |
Your server stores no personal credentials. It uses the header for exactly this call and forgets it.
Network boundaries
- Inbound, only AISRV inside the cluster reaches your server (ClusterIP). No ingress, no external exposure.
- Outbound, your server may reach only its target system. The MCP gateway enforces an egress allowlist; network policy, DNS, TLS trust and firewall must allow exactly this path. Build the server so that it needs nothing else – no telemetry, no fonts, no third-party SDKs phoning home.
- TLS to the target system is mandatory when the path leaves the cluster. Import private CAs into the container truststore.
State and concurrency
- No sessions. Every request is complete: header, tool, parameters. No cookies, no login state.
- No cache across users. What user A retrieved must not be served to user B from a cache. If you cache, only within a request.
- Parallel and idempotent. Several users call simultaneously; read tools must be repeatable at will.
- Horizontally scalable. Without state, several replicas can run.
Operational requirements
| Requirement | Implementation |
|---|---|
| HTTP transport | MCP over HTTP on the configured port, path /mcp |
| Non-root | Container runs without root privileges, read-only filesystem where possible |
| Probes | Readiness and liveness (tcpSocket or HTTP) configurable in the Helm entry |
| Configuration | Via environment variables; secrets from Kubernetes secrets |
| Logging | Structured to stdout; never headers, tokens, passwords or document content; credentials at most at DEBUG in diagnostic runs |
| Errors | Errors of the target system (401, 403, 404, 5xx) become tool results with a clear cause, not crashes |
| Size limits | Bound results per tool call (characters, hits); paginate or truncate large documents |
What belongs to basebox – and what to you
| basebox | Your connector |
|---|---|
| Token validation, user identity | API calls to the target system |
| Store and insert per-user credentials | Pass the header on unchanged |
| Enablement per organisation and per app | Describe tools clearly |
| Block write tools by default | Separate read and write tools cleanly |
| Frame results as data | Deliver plain text without active content |
| Audit log per call | Structured operational log without secrets |
| Enforce the egress allowlist | Need only the target system |
Next: Authentication · Connect an MCP server