External MCP servers
Add external MCP servers and APIs to a workspace, such as GitHub, Linear, and internal tools, so its agents can call their tools and a rule answers each call.
Oxagen connects outbound to the external MCP servers a workspace adds. The workspace's agents call their tools through Oxagen, and a rule answers each call. This is the inverse of connecting, which covers MCP clients calling the Oxagen MCP server.
How it works
Each server is a folder under tools/servers/<server>/ in the workspace's steering repo. A steering PR adds or changes the folder, and nothing reaches an agent until that PR merges. Studio drafts and review builds the folder and opens the PR.
When the workspace publishes the merged version, Oxagen's MCP endpoint serves the server's tools to the workspace's agents on enrolled machines. The agent's harness reaches them through the oxagen entry that enrollment adds. See Enrolled machines.
Each served tool is named <server>__<tool>. A server whose exposure mode is search lists three tools in place of its full list: <server>__search, <server>__describe, and <server>__call. search returns up to 10 matching tools, and call runs the one it names.
Every call to a served tool takes these steps:
- Oxagen checks the off switches on the Off switches tab of the Agents page. A switch on the tool, the server, the connection, or the operator stops the call.
- Oxagen checks the workspace's policies against the real tool. A rule can deny the call, or hold it for a person's approval. Oxagen sends a held call only when the agent calls the tool again after the approval.
- Oxagen adds the credential the server names and sends the call. The agent never sees the credential.
- Oxagen records the call as a governed action, whether it ran, was denied, waited for approval, or failed.
Sources
The [source] table in server.toml says where the tools come from:
type | What it is |
|---|---|
remote | A remote MCP server over streamable HTTP (transport = "http"). Review refuses sse, the older transport. |
registry | A package from an MCP registry, named <namespace>/<name>. With machines, it runs on enrolled machines. |
local | A command that runs on enrolled machines. See Local servers. |
openapi | An OpenAPI 3.0 or 3.1 document, or Swagger 2.0 |
graphql | A GraphQL schema |
grpc | A protobuf package |
A server inside a private network reaches Oxagen through a relay that runs in that network. See Servers in a private network.
Authentication
The [auth] table in server.toml says how Oxagen signs in to the server:
| Field | Values |
|---|---|
mode | none, service for one credential every run shares, or operator-oauth for the operator's own token |
scheme | oauth, bearer, basic, or header. An OpenAPI server names a key of its document's components.securitySchemes. |
header | The header that carries the credential, when scheme is header |
credential | oxagen:credential/<name>, a credential the workspace holds |
A local server, or a registry server with machines, needs no [auth] table. Every other server needs one, so write mode = "none" for a server that takes no credential.
Store a credential with set_mcp_credential: a service secret, or an OAuth client's id and secret. Oxagen encrypts each secret, refreshes an OAuth token before it expires, and server.toml names the credential by reference only. See Keep credentials out.
Servers added with register_mcp_server
register_mcp_server adds a server to the workspace directly. It takes a transportType of streamable-http or stdio, and an authStrategy of none, bearer, or header. Only an org Owner or a workspace Admin can call it, so an API key you create cannot.
Once the workspace's tools live in its steering repo, a remote server added this way opens a steering PR instead, and the server stays off until that PR merges. A server added before the workspace had a steering repo stays a row in Oxagen until a migration steering PR moves it into the repo. See Move connected servers into the steering repo.