Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Build connectors

Applies to

Product: Cloud · Server · Audience: Developer / Integrator

basebox connectors are MCP servers. This section explains how to build one that fits basebox: architecture, per-user authentication, read and write tools, permissions and the shipped connectors as templates. If you follow the rules, you get a connector that can be enabled in any app without administrators or data protection having to ask questions.

What a connector is in basebox

A connector is an MCP server (Model Context Protocol) that provides tools to the assistant – such as "search page", "read issue", "search mailbox". The application server AISRV is the MCP client: it fetches the tool list, offers it to the model, intercepts calls, inserts the user's credentials, calls the server over HTTP and frames the result as data. How that works in detail: MCP client · Authorization flow.

The six rules

Rule What it means Page
1. Stateless between basebox and the target system The server keeps no sessions, no cache across users, no copy of permissions Architecture
2. Pass credentials through, do not own them Personal tokens arrive per request in the Authorization header and go to the target system unchanged; never store, never log Authentication
3. Reading returns small, structured data Search, retrieve, list with bounded results as plain text with stable references Read access
4. Writing is separate and explicit Dedicated tools for changes, idempotent, no bulk operations; off by default per app in basebox Write access
5. The target system decides on permissions If it refuses, the connector returns that as a result – it circumvents nothing Permissions
6. Only one destination on the network The server reaches exactly its target system; the MCP gateway blocks everything else Architecture

The path to a finished connector

  1. Check the target system. Does it have an API with per-user authentication, search and targeted retrieval? See Business systems → What a system should provide.
  2. Decide the access model – personal credentials (the norm) or service account (only for generally accessible content).
  3. Design the tools – read-only at first. Names, descriptions and parameters such that a language model uses them correctly.
  4. Build the server – HTTP transport on /mcp, non-root container, readiness and liveness probe, no credentials in logs.
  5. Test locally against the target system – with a token that is allowed little, and check that refusals come back cleanly.
  6. Deploy – on basebox Server via Helm as a byo connector by the Platform Operator (Connect an MCP server); in the Cloud in coordination with basebox.
  7. Have it enabled – the administrator configures it, tests the connection and enables the connector per app.
  8. Only then add write tools, once the need is clear.

What you do not have to build

  • Permission management – that stays with the target system.
  • User management or login screens – users enter their token in basebox; basebox delivers it to you per request.
  • Prompt-injection protection in the sense of filters – basebox frames your results as data. Your contribution: plain text, bounded size, no active content.
  • Audit logging – basebox records every tool call with user, tool, target, result and timestamp.

Templates

The shipped connectors show the patterns: web search (one provider, egress allowlist, text-only results), DokuWiki (personal credentials, search and read), YouTrack (hosted MCP, permanent token, read and – if enabled – write), e-mail (personal mailbox login), calculator (no sign-in). Worked out under Examples.

Next: Architecture