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

// integration

MCP client

Applies to

Product: Cloud · Server · Audience: Developer / Integrator · Security reviewer

How the basebox assistant works as an MCP client: discovering tools, deciding when to call a tool, feeding results back – and what users see of it in the interface. The Model Context Protocol (MCP) is the standard through which basebox connects connectors; every connector is an MCP server, the application server AISRV is the client.

The roles

Role Who Task
MCP client AISRV (the MCP gateway in basebox) Connects to MCP servers, fetches their tool list, executes calls, preserves permissions
MCP server A connector – web search, DokuWiki, YouTrack, your own Provides tools and talks to the connected system
Model The language model Decides based on the question whether and which tool to call

Flow of a tool call

  1. Request. A user sends a message; AISRV validates the token and thus knows the user_id.
  2. Determine tools. AISRV loads two lists and forms the intersection: which connectors the current app enables, and which the user has activated (and – where necessary – equipped with their own credentials). Only these tools exist for this conversation.
  3. Offer to the model. The permitted tools are described to the model together with the prompt. The model decides whether a tool helps.
  4. Intercept. If the model decides on a call, basebox does not execute it blindly but first inserts this user's credentials into the connection configuration – producing an Authorization header (Bearer or Basic).
  5. Call. AISRV sends POST /mcp to the MCP server with this header. The server passes it on to the connected system; the system applies its own permissions.
  6. Result as data. The tool result comes back and is framed as data – never as instructions – before it is presented to the model for the final answer. That is the safeguard against prompt injection via tool results.
  7. Answer. The answer is streamed to the user.

The sequence diagram with all steps and the security properties are under MCP permission and authorization flow.

What the client guarantees

  • No shared admin token. Every call carries the requesting user's credentials; basebox never filters centrally fetched data per user.
  • No caching across users. Credentials are loaded fresh per request; results are not shared between users.
  • Write access off by default. Tools that create, change or delete are disabled per app until an administrator enables them.
  • Egress allowlist. A connector container reaches only the hosts of its declared target system; the MCP gateway blocks everything else – even if the connector tried.
  • Immediate revocation. If a token is revoked or an account deactivated, the next call fails; there is no lingering session.
  • Credentials never in logs – except at level DEBUG in targeted diagnostic runs.

What users see

  • Under the "+" icon in the input bar, the connectors enabled for them and the current app – that is also where they enter personal tokens.
  • During a call, a progress notice: which connector, which tool, for how long.
  • For web search, a consent prompt before the first search; the "Web" switch resets when leaving the chat.
  • Links to content of the connected system open in a new tab.
  • In the audit log, every tool call as metadata (organisation, user, tool, provider, result, timestamp) – for web search without the query text.

Transport and requirements for MCP servers

basebox talks to MCP servers over HTTP: endpoint usually /mcp, in the cluster e.g. http://mcp-<name>:8000/mcp. An MCP server that is to fit basebox must

  • support the HTTP transport configured by the chart,
  • pass the Authorization header on to the target system unchanged (for connectors with personal credentials),
  • describe tools clearly (name, purpose, parameters) so the model uses them correctly,
  • return results bounded and structured,
  • run as a non-root container and serve readiness/liveness probes.

How to deploy such a server: Connect an MCP server. How to design it: Build connectors.

What the client does not do

  • It keeps no copy of the connected system's permissions.
  • It does not map basebox roles to roles of the target system.
  • It does not call tools without a decision by the model – and the model sees only what app and user have enabled.
  • It is not available via the OpenAI-compatible API: API requests run on behalf of the organisation, not a person, and therefore carry no personal connector credentials. Tool calling via the API means functions that your application defines and executes.

Next: MCP overview · Authorization flow · Introduction to web search security