MCP servers

The MCP servers OpenAgentics ships, their authentication models, and tool-level policy.

OpenAgentics ships nine first-party Model Context Protocol (MCP) servers — the oap-*-mcp servers in services/mcps/ — plus two bundled external helpers (sequential_thinking and aws_knowledge) that your agents can call. The chat pipeline selects tools through a three-layer cascade rather than exposing every tool at once, so you can leave many servers enabled without overwhelming the model.

OpenAgentics is a self-hosted platform. This page describes the bundled servers and their static-credential authentication model.

Built-in servers

Each first-party server runs as a subprocess inside the mcp-proxy service, built from services/mcps/oap-*-mcp. The source of truth for the server registry is services/openagentic-mcp-proxy/src/mcp_manager.py. The nine first-party servers below are enabled by default, alongside two bundled external helpers noted in the table.

Server	Purpose	Authentication	Admin-only
`openagentic_web`	Web search and fetch, backed by the bundled self-hosted SearXNG metasearch service (no API key)	None (`SEARXNG_URL`)	No
`openagentic_admin`	Platform administration: Postgres, Redis, Milvus inspection, user sessions, audit	None (gated by proxy RBAC)	Yes
`openagentic_aws`	AWS operations through `call_aws` and `suggest_aws_commands`	Static IAM credentials	No
`openagentic_azure`	Azure Resource Manager, Compute, Storage, Cost Management, Key Vault	Static service principal	No
`openagentic_gcp`	Compute, Cloud Resource Manager, Storage, Billing, Vertex AI, Monitoring	Static service account	No
`openagentic_kubernetes`	Cluster operations (read-only against the OpenAgentics namespace)	In-cluster service account	Yes
`openagentic_github`	Repositories, issues, pull requests, branches, code search	Personal access token	No
`openagentic_prometheus`	PromQL queries: metrics, alerts, targets, rules	None (proxied to `PROMETHEUS_URL`)	Yes
`openagentic_loki`	LogQL queries: log search, tail, analyze	None (proxied to `LOKI_URL`; requires `LOKI_URL` to be set)	Yes
`sequential_thinking` (bundled external, disabled by default)	Chain-of-thought reasoning — the upstream `@modelcontextprotocol/server-sequential-thinking` package, run via `npx`. Enable by setting `SEQUENTIAL_THINKING_MCP_DISABLED=false`.	None	No
`aws_knowledge` (bundled external)	AWS documentation and best-practice lookup — AWS-hosted remote service	None	No

Note: Code execution is not an MCP server. It runs as a separate sandboxed service, so there is no oap-code-mcp. Diagrams are rendered inline by the chat UI rather than by a dedicated diagram server.

Authentication

In the self-hosted build, cloud MCP servers authenticate with static service-account or static credentials. There is no identity-provider-based on-behalf-of (OBO) token exchange in the self-hosted build: cloud actions run as the configured service identity, not as the individual calling user.

Supply credentials either through mounted host CLI configuration or through environment variables.

Server	Mounted host config	Environment variables
`openagentic_aws`	`~/.aws` (read-only) with `AWS_PROFILE`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
`openagentic_azure`	`~/.azure` (read-only)	`AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_SUBSCRIPTION_ID`
`openagentic_gcp`	`~/.config/gcloud` (read-only)	`GCP_CREDENTIALS_JSON` (inline JSON) or `GCP_CREDENTIALS_FILE` (path to a service-account key)
`openagentic_kubernetes`	`~/.kube` (read-only)	Pod service account when running in-cluster
`openagentic_github`	—	`GITHUB_TOKEN`
`openagentic_prometheus`	—	`PROMETHEUS_URL` (defaults to `http://prometheus:9090`); optional `PROMETHEUS_USERNAME` / `PROMETHEUS_PASSWORD`
`openagentic_loki`	—	`LOKI_URL` (no default — must be set, e.g. `http://loki:3100`); optional `LOKI_USERNAME` / `LOKI_PASSWORD`

When you do not provide credentials in the environment, the proxy falls back to env files under ~/.openagentic/cloud-secrets/ (aws.env, azure.env, gcp.env).

Note: The shipped compose sets no default for LOKI_URL. The Loki server starts, but every Loki query errors (missing http:// protocol) until you set LOKI_URL — for example LOKI_URL=http://loki:3100 when running the bundled --profile monitoring Loki. Prometheus needs no such setting; PROMETHEUS_URL defaults to the in-cluster/Compose prometheus service.

Important: Identity-provider-based OBO for cloud MCP servers is an enterprise feature and is not part of the self-hosted build. To grant per-user cloud access in a self-hosted deployment, you would need to build a credential broker, which is out of scope.

Every MCP call is logged to the audit trail.

Tool selection

Tools are not all sent to the model at once. The chat pipeline applies a three-layer cascade (referred to as t1/t2/t3) that routes by intent, narrows by semantic search, and enforces a hard ceiling. This is distinct from context-budget management, which is a separate system.

Intent routing (L1). Regular-expression and keyword patterns classify the query and select candidate servers. For example, a query containing kubectl targets the Kubernetes server, while a query mentioning logs targets Loki. This typically narrows the full tool catalog (on the order of ~160 tools across the enabled servers) to roughly 8–40 candidates.
Semantic search (L2). The user query is embedded and compared against tool embeddings using cosine similarity, scoped to the servers from L1. A score-gap cutoff drops the irrelevant tail.
Hard ceiling (L3). The model never receives more than 15 tools in a single turn, regardless of semantic scores.

PostgreSQL with the pgvector extension (HNSW index) is the primary source of truth for tool embeddings. Milvus and Redis act as fallbacks for resilience.

Note: Milvus is optional. The shipped Compose stack runs pgvector-only by default (SKIP_TOOL_SEMANTIC_CACHE=true), and tool selection works without Milvus. Enable Milvus only for large embedding or RAG workloads — bring up the milvus profile (docker compose --profile milvus up -d) and set MILVUS_ENABLED=true with SKIP_TOOL_SEMANTIC_CACHE=false. When Milvus is enabled but unreachable, the API exits after its retry budget rather than silently degrading.

Tool-level policy

Every MCP call passes through mcp-proxy, which applies enforcement layers before a tool runs.

Read-only mode. The MCP_READ_ONLY_MODE flag (overridable from the admin console) blocks mutating calls on the cloud-infrastructure servers (AWS, Azure, GCP, Kubernetes) by tool-name pattern. Other servers are unaffected.
Server-level access control. Admin-only servers (openagentic_admin, openagentic_kubernetes) are denied to non-admin users. The proxy enforces this through MCPAccessControlService and the mcp-auth middleware before routing a request.
Kubernetes write protection. The Kubernetes server is read-only against the OpenAgentics system namespace. In the Helm chart, the proxy’s service account is bound to a read-only ClusterRole, so the API server denies writes as a defense-in-depth measure.

Enable servers per environment

Each server has an OpenAgentic_<NAME>_MCP_DISABLED environment flag, read by the proxy at startup. Set it to false to enable a server and true to disable it. A Redis key (mcp:server:enabled:{server_name}) can override the build-time state at runtime so that changes survive restarts.

Environment	Default servers	How to change
Docker Compose	All nine first-party servers (`openagentic_web`, `openagentic_admin`, `openagentic_aws`, `openagentic_azure`, `openagentic_gcp`, `openagentic_kubernetes`, `openagentic_github`, `openagentic_prometheus`, `openagentic_loki`) plus `aws_knowledge`. The cloud servers only become usable once you supply credentials, and Loki needs `LOKI_URL`. `sequential_thinking` ships disabled (`SEQUENTIAL_THINKING_MCP_DISABLED=true`).	Set the `OpenAgentic_<NAME>_MCP_DISABLED` flags. See Docker.
Helm (Kubernetes)	`openagentic_web`, `openagentic_admin`, `openagentic_kubernetes`, `openagentic_prometheus`. The chart disables the cloud servers (aws, azure, gcp), `openagentic_github`, and `openagentic_loki` by default, since a barebones cluster has no credentials or Loki endpoint for them.	Set the same flags in the `mcp-proxy` template. See Kubernetes.

Note: The MCPS_ENABLED variable is documentation/UI display only and is not read by the proxy when it decides which servers to spawn. The actual gate is the per-server OpenAgentic_<NAME>_MCP_DISABLED flag. (The Helm chart’s mcps.enabled string still lists a legacy knowledge token; there is no knowledge server — it was removed upstream and replaced by the per-tool meta cascade, so that token is inert.)

Credentials are never baked into the image; they come from mounted host configuration or the admin panel.

Caution: Air-gapped installations must keep the cloud servers (openagentic_aws, openagentic_azure, openagentic_gcp) disabled, because they require outbound calls to cloud control-plane APIs.

Bring your own server

You can register additional MCP servers without rebuilding the image.

In the admin panel, paste a standard MCP configuration block in the format { "mcpServers": { ... } }.
mcp-proxy installs the server and registers its tools.
Each tool description is embedded into pgvector for semantic routing.
The same tool-level policy layers apply to the new server, just as they do to the first-party servers.

What’s next

Deploy the stack with Docker or Kubernetes.

Note: OpenAgentics is not FedRAMP authorized.