Add a Connector

Register a Remote endpoint or run a container as a Managed Server, then edit or remove it.

Agentic Friendly

Adding a Connector requires mcp.server.create in the selected tenant. Tenant administrators have this permission; a custom role can delegate it. Editing and deletion require mcp.server.update and mcp.server.delete, respectively. See the MCP permission catalogue.

Adding a server makes it available to the whole organization. It does not give anyone access to the system behind it. Each member still links their own credential, unless the server is registered as unauthenticated.

Open the section

In the Portal sidebar, select Connectors. The list shows every server the organization has, with its runtime, its status, and whether you have linked a credential to it.

Select Add connector.

Start from a preset

The create page opens with a preset picker. A preset fills in the form for a well-known Connector so you only have to review it.

PresetRuntimeAddress or image
LinearRemotehttps://mcp.linear.app/mcp
Linear (read-only)Remotehttps://mcp.linear.app/mcp/readonly
NotionRemotehttps://mcp.notion.com/mcp
GitHubRemotehttps://api.githubcopilot.com/mcp
Context7Manageddocker.io/mcp/context7:latest
OutlookManagedghcr.io/softeria/ms-365-mcp-server, pinned by digest
Microsoft TeamsManagedghcr.io/softeria/ms-365-mcp-server, pinned by digest
SharePointManagedghcr.io/softeria/ms-365-mcp-server, pinned by digest
SlackRemotehttps://mcp.slack.com/mcp
CustomEitherNothing prefilled

The Context7 preset also sets the credential mode to Unauthenticated, because its upstream service has no account to hold a credential for. The other presets keep the default of one credential per user.

The Outlook, Microsoft Teams, SharePoint, and Slack presets also prefill scopes and a tool allowlist, and they need an app registration. See Use your own app registration.

Add MCP Server with the Context7 preset selected, Managed runtime, and Unauthenticated credential mode

Choose Custom to configure a server yourself.

Fill in the basic information

Every server, of either runtime, needs these fields.

FieldRule
RuntimeManaged or Remote. Permanent once saved.
NameLowercase letters, numbers, and dashes, starting and ending with a letter or number. Up to 63 characters. Unique within the organization. Permanent once saved.
Display nameThe label people read. Up to 200 characters. Editable.
DescriptionOptional. Up to 500 characters.
Credential modeEach user links their own or Unauthenticated. Defaults to each user linking their own. Permanent once saved.

The name is the identifier the organization's own references are written against, so it cannot be changed later. The display name carries any wording you want to revise.

Credential mode

Credential mode decides what the MCP Gateway sends to the system behind the server.

Each user links their own is the ordinary choice. Every member supplies a User Credential for the upstream system before they can see or call the server's tools.

Unauthenticated is for an upstream system that has no account to authenticate against, such as a public documentation service. The Gateway sends it no Authorization header, nobody links a credential to it, and no member has to link anything before reaching its tools. An attempt to link one is refused with mcp_server_needs_no_credential.

Choose it only for an upstream system that genuinely accepts unauthenticated calls. One that wants authentication after all answers 401, which reaches the caller as a refused credential they cannot replace.

Choose Unauthenticated rather than asking members to paste a placeholder token. A placeholder sends an invented identity to a system that never asked for one.

The mode is fixed once the server is saved. The edit form shows it and does not offer to change it. To move a server to the other mode, delete it and add a new one, which gives it a new identifier that every member and every Agent has to be pointed at again.

Add a Remote Server

A Remote Server has one runtime field.

Address is the full MCP endpoint, including the path. For example, https://mcp.linear.app/mcp.

The address must satisfy these rules:

  • It uses the http or https scheme, written in full. A bare hostname is refused.
  • It has no leading or trailing whitespace.
  • It carries no username or password. Credentials belong in a User Credential, not in the URL.
  • Its host is publicly resolvable. Private IP ranges, localhost, single-label hostnames, and cluster-internal names such as svc.cluster.local are all refused.
  • It is at most 2048 characters.

A refused address returns mcp_server_address_invalid and names the rule it broke.

With the platform's network policies on, the BSQAI API and the MCP Gateway reach addresses outside the cluster only on the ports in LLM_BACKEND_NETWORK_POLICY_EXTERNAL_PORTS, 443 and 80 by default. A Remote Server on another port, such as https://mcp.example.com:8443/mcp, is accepted but never answers, and its calls fail with mcp_server_unreachable until the platform operator adds the port.

Add a Managed Server

A Managed Server needs the container definition as well.

In a tenant organization, the server runs in the tenant's namespace and counts against its compute quota. The tenant's runtime must be ready for Connectors first. Until it is, or while the tenant is being deleted, the request is refused with 409 mcp_server_tenant_not_ready and nothing is recorded. Try again once the tenant is ready.

FieldRule
ImageRegistry-qualified, with a tag or digest. docker.io/mcp/context7:latest is accepted. mcp-probe:v1 is refused.
PortThe port the image itself listens on, between 1 and 65535.
PathWhere the image serves MCP. Defaults to /mcp. Must start with a slash.
ArgumentsOne per line. Optional.

A rejected image returns mcp_server_image_invalid and names the reference rule it broke. The API applies the same image-reference rules as the operator CRD. Form acceptance does not prove that the registry is reachable or that the image exists; those failures appear in the Managed Server status.

Four settings decide whether the container ever answers.

The image must already serve Streamable HTTP. Most MCP images start in stdio mode. Something has to switch the image out of stdio, and the switch differs per image. Context7 reads MCP_TRANSPORT=http from the environment. The GitHub server takes http --port 8080 as arguments. Without the switch the container starts, reports healthy, and never listens on the port.

Arguments replace the image's default command, and the entrypoint stays. An image whose CMD is node dist/index.js needs that listed first, then your own flags. Passing only a flag runs the entrypoint with that flag and the container dies.

Port must be the port the image listens on, not one you pick.

Path must be where the image serves MCP. Usually /mcp.

Pull from a private registry

If the registry asks for a sign-in to pull the image, open Pull from a private registry and enter the Username and the Password or access token. The section names the registry the credential is for: the host in Image, or Docker Hub when Image names no host.

The credential is used only to pull the image. The Connector's container never sees it, and no endpoint returns the password. Nothing is checked when you save, so a wrong credential shows up later as an image pull failure in the server's status. The platform does not renew it: use a long-lived, read-only token where the registry offers one. A short-lived token, such as an Amazon ECR authorization token, stops working when it expires.

The detail page shows Registry credential as <username> at <registry>, or None.

On edit, an empty password keeps the stored one while the username and the registry stay the same. Changing the username, or an Image from another registry, needs the password again. Clearing the username removes the credential when you save; if the image is private, new instances of the Connector can then no longer pull it.

Outbound access

With the platform's network policies on, a Managed Server reaches cluster DNS and the addresses outside the cluster that the platform operator allows, on ports 443 and 80 by default. Other destinations are refused. On Cilium, that includes services inside the cluster; on Calico, the default 0.0.0.0/0 also admits pod addresses on those ports, so a Calico site lists its external ranges instead. An image that calls its upstream on another port fails at call time until the platform operator adds the port.

Environment variables

The Environment card takes one KEY=VALUE per line. Names must start with a letter or underscore and contain only letters, numbers, and underscores.

Values are write-only. They go into a Kubernetes Secret, and no endpoint returns them. A read reports names only, each marked as configured. The BSQAI API can write the Secret but not read it, so this is enforced rather than promised. The one identity that can read an environment Secret is the platform's internal Connector reconciler, and only in the shared Connector namespace. It reads the Secret to move a server into its organization's tenant namespace once that tenant is ready for Connectors, for example when a tenant is provisioned for an organization that already has Connectors. It copies the image pull credential the same way.

Because values are not readable, they are not recoverable. Record them wherever you keep other secrets.

If the values cannot be written to the cluster, the whole request fails with mcp_server_environment_not_stored and no server is created. This is the one part of a Managed Server that is not converged later, because the values exist nowhere else.

Security context

Every Connector container runs as a non-root user, with a read-only root filesystem and all capabilities dropped. Some images cannot survive that.

The Security context (advanced) section is the exception mechanism. It holds four settings.

SettingEffect
Run as user IDSets the numeric user the container runs as. Leave blank to keep the default.
Run as group IDSets the numeric group. Leave blank to keep the default.
Require a non-root userUndecided keeps the default. Switch it off only for an image that must run as root.
Read-only root filesystemUndecided keeps the default. Switch it off for an image that writes to its own filesystem.

An undecided setting leaves the platform's decision alone. Change one only when the image genuinely cannot run hardened. The container runs somebody else's code with your organization's credentials in its environment.

Context7 needs Run as user ID set to 1000 because the image ships no user of its own.

Expanded security context and environment sections on the Managed create form

Use your own app registration

Some providers, such as Microsoft Entra ID and Slack, do not let the platform register itself as an OAuth client. For those, register an app with the provider and enter it on the Connector. Members then sign in through that app when they link. The Use your own app registration section appears when the credential mode is Each user links their own.

FieldRule
Redirect URIShown, not entered. Register this exact address with the provider's app. It is the same for every Connector in the deployment
Client IDVisible ASCII characters without spaces, up to 255 characters. Clearing it on edit removes the whole app registration
Client secretOptional. Up to 1024 characters. Write-only, so it is never shown again. On edit, an empty field keeps the stored secret and a new value replaces it. After a change to the Client ID or the Authorization server, enter the secret again, or the save is refused with mcp_server_oauth_client_invalid
ScopesSeparated by spaces or new lines. Up to 100 scopes of up to 255 characters each. Members are asked to grant exactly these. Leave it empty to request the provider's default
Authorization serverThe provider's issuer URL. Required, because the client secret and members' sign-ins only ever go to the authorization server you name

Changing the Client ID or the Authorization server, or adding or removing the app registration, makes members who linked with OAuth link again once their current access expires. Rotating only the secret does not affect members. A registration the platform cannot use is refused with mcp_server_oauth_client_invalid, and the message names the problem. An Unauthenticated Connector takes no app registration.

For the provider-side setup of the Microsoft 365 and Slack presets, see Connect Microsoft 365 and Slack.

Wait for a Managed Server to become ready

Open the server. Its status is one of four values.

StatusMeaning
ReadyThe workload is up and completed an MCP handshake.
Not readyThe workload exists but is not serving.
Status unknownA Managed Server the cluster has not reported on yet. Normal for a few seconds after creation.
Not reportedA Remote Server. It runs outside the platform and reports nothing. This is normal and permanent.

The detail page refreshes an unready Managed Server on its own for a minute, then offers a Refresh status button.

Creating a server records your intent. Once the organization's tenant runtime is ready, it succeeds even when the cluster is busy or unreachable, and the workload converges on the record afterwards. Status stays empty until the cluster catches up.

A new server that would exceed the tenant's compute quota is recorded but stays Not ready, and its status names the quota as the reason. Raise the quota or remove another workload, then wait for the server to start.

If a Managed Server never becomes ready, check the four settings above. A container that starts healthily and never answers is almost always still in stdio mode, or listening on a different port.

Managed MCP Server detail page in the ready state showing the status card

Edit a server

Select Edit Connector on the detail page, or the edit icon at the end of the server's row in the Connectors list. Both open the same edit form. Runtime, name, and credential mode are shown as fixed. Everything else is editable.

The row's edit and delete icons appear when you point at or focus the row, and stay visible on touch screens. Each appears only when you hold the permission for its action.

The edit form replaces what you send. Fields you clear are cleared on the record. Environment variables are the deliberate exception.

An untouched edit form sends no environment at all, and the stored environment is preserved. To change it, select Replace environment. That replaces every variable at once, so retype every one you want to keep. Values cannot be read back, so a variable you leave out is a variable you remove. Keep the stored environment abandons the replacement.

Edit form environment card listing the currently set variable names

A server cannot change runtime. Editing a Managed Server as a Remote one, or the reverse, returns mcp_server_runtime_mismatch. To change runtime, delete the server and add a new one. The new server has a different identifier, so every member links it again where the credential mode calls for a link, and every Agent referencing it must be updated.

Delete a server

Select Delete on the detail page, or the delete icon at the end of the server's row in the Connectors list, and confirm. Both open the same confirmation, which names the server. If the deletion fails, the confirmation stays open with the error, and you can try again. Deleting removes the Connector and every User Credential linked to it. It cannot be undone. For a Managed Server, the workload is removed too.

Create a server with the API

The create form has a Create this with the API instead section that shows the exact request the form will send, built from what you have typed. Environment values, the client secret, and the image pull password are masked in that preview, so replace each placeholder before running it.

The equivalent request for a Remote Server:

export BSQAI_TOKEN=sk-bsq-v1-...

curl -X POST "https://api.<platform-domain>/v1/mcp/servers" \
  -H "Authorization: Bearer $BSQAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "remote",
    "name": "linear",
    "display_name": "Linear",
    "credential_mode": "per_user",
    "address": "https://mcp.linear.app/mcp"
  }'

And for a Managed Server:

curl -X POST "https://api.<platform-domain>/v1/mcp/servers" \
  -H "Authorization: Bearer $BSQAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "managed",
    "name": "context7",
    "display_name": "Context7",
    "credential_mode": "anonymous",
    "image": "docker.io/mcp/context7:latest",
    "port": 8080,
    "path": "/mcp",
    "env": {"MCP_TRANSPORT": "http", "PORT": "8080"},
    "security": {"run_as_user": 1000}
  }'

For an image from a private registry, add "image_pull_credential": {"username": "<registry-user>", "password": "<token>"}. A read returns only registry and username.

credential_mode accepts per_user or anonymous and defaults to per_user. It is a create-only field: an update that sends it is rejected with 422.

Create an API key under API Keys in the Portal's account menu, at the bottom of the sidebar, and give it mcp.server.create. The key works only while you also hold that permission. See Create and use an API key.

On this page