Licensed to be used in conjunction with basebox, only.
// integration
Examples
Applies to
Product: Cloud · Server · Audience: Developer / Integrator
The shipped connectors – web search, DokuWiki, YouTrack, e-mail, calculator – as worked examples of the patterns in this section. Each shows a different combination of access model, tool class and network boundary.
Overview
| Connector | Access model | Tools | Network target | Shows above all |
|---|---|---|---|---|
| Web search | No user sign-in; optional organisation API key | Read (search) | Exactly one provider host | Egress allowlist, text only, no query logging |
| DokuWiki | Personal (username/password or token) | Read (search, read page) | The wiki's XML-RPC URL | Header pass-through, permissions at the source system |
| YouTrack | Personal (permanent token) | Read and – if enabled – write | Hosted JetBrains MCP | Hosted server, write tools separate |
| Personal (mailbox login) | Read (search, read message) | IMAP host from Helm | Very sensitive data, strictly per user | |
| Calculator | None | Pure function | No external target | Tool without a target system |
Web search – one provider, text only
Structure. The connector reaches exactly one search provider – Staan by default (api.staan.ai), alternatively DuckDuckGo (duckduckgo.com, html.duckduckgo.com, lite.duckduckgo.com). The MCP gateway enforces this allowlist: the container cannot reach any other host even if it tried. The connector never fetches web pages itself; even the detailed mode for page content is served by the provider's API.
Access. Users store nothing. Optionally the administrator enters an organisation API key; if left empty, searches run on the shared basebox quota. A rejected key produces an explicit error – no silent fallback.
Results. Up to 10 hits per query, structured (title, URL, snippet; in detailed mode page content as Markdown, size-bounded). No scripts, no active content.
Privacy. The query leaves the environment via basebox's connection – without user identity and user IP. The audit log records organisation, user, tool, provider, result and timestamp, not the query text.
What to take from it: where a provider has an API, use it instead of scraping; declare exactly one target; bound results; log metadata, not content. Details: Web search · Introduction to web search security.
DokuWiki – personal credentials, reading
Structure. The Platform Operator sets the wiki's XML-RPC URL via Helm (global.dokuwiki.rpcUrl) and enables doku-rs. The administrator switches the connector on and enables it in apps.
Access. Each user stores their own wiki account (username/password or token). basebox puts it into the header per request; the connector passes it on to the XML-RPC interface. What the user may not see in the wiki they do not see here either – DokuWiki decides.
Tools. Search pages, read page. Results: page ID, title, excerpt or content, link. Plain text.
What to take from it: configuration (URL) with operations, credentials with the user, permissions with the wiki. Details: DokuWiki.
YouTrack – hosted server, writing separate
Structure. YouTrack uses the MCP integration hosted by JetBrains; no workload runs in the basebox cluster. The administrator configures the endpoint and enables it.
Access. Each user generates a permanent token in YouTrack (guide) and enters it in basebox. Requests appear in YouTrack under their name.
Tools. Query issues (read) and update issues (write). The write tools are off by default per app; an administrator enables them deliberately – for example only in an app for the support team.
What to take from it: even an externally hosted MCP server fits the model as long as it accepts per-user credentials. Keep read and write tools separate. Details: YouTrack.
E-mail – sensitive data, strictly per user
Structure. The Platform Operator sets IMAP host, port and connection type via Helm (global.email.*) and enables email-rs. Mailbox credentials do not belong in this file.
Access. Each user stores their own mailbox login in basebox. The connector speaks IMAP with exactly these credentials; nobody sees someone else's mailbox.
Tools. Search and read messages – read-only. Results bounded (sender, subject, date, excerpt), plain text.
What to take from it: with particularly sensitive data, the personal access model is the only option, writing stays out, and results are kept short.
Calculator – tool without a target system
Structure. A pure function: expression in, result out. No external service, no credentials, no network target.
What to take from it: not every connector needs authentication. Where a tool only calculates or transforms, "none" is the right access model – and the egress allowlist is empty.
And your own connector
A connector for an internal business system follows the DokuWiki pattern: base URL via Helm, users' personal tokens, tools search, get, list, results as structured text with links, refusals as results. Only once that runs do write tools follow the YouTrack pattern. Deployment: Connect an MCP server.
Back to the overview: Build connectors