Enterprise MCP Server

Odigos MCP lets AI agents (Cursor, Claude Desktop, and others) inspect and configure a live Odigos cluster. The endpoint is mounted at /mcp on the UI service (port 3000).

Requirements

Odigos Enterprise installed with a valid on-prem token
Network access to the Odigos UI service (typically via port-forward or an in-cluster / load-balancer URL)
An MCP-compatible client (for example, Cursor)

Connect from Cursor

The simplest way to connect locally is to port-forward the UI service, then point your MCP client at the /mcp endpoint.

Port-forward the UI

kubectl port-forward -n odigos-system svc/ui 3000:3000

Add the MCP server in Cursor

Open Cursor Settings → MCP and add a server with a streamable HTTP URL:

{
  "mcpServers": {
    "odigos": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

For a remote UI (for example, behind a load balancer), use that base URL instead: https://<your-ui-host>/mcp.

Verify the connection

In your AI agent’s MCP tool registry, open the MCP server connections — the Odigos server should be listed along with its MCP tools.

Ask your cluster a question

Query Odigos directly through MCP, for example: “Which sources are unhealthy in the default namespace?”

Access modes

The MCP server starts in read-only mode by default. Read operations always work; write operations are blocked until an operator switches it to read-write (see Configuration).

Mode	Behavior
`read-only` (default)	Safe inspection only. Write requests are rejected.
`read-write`	Mutating operations are allowed. Use only when you trust the agent to change the cluster.

This setting is independent of the UI’s read-only mode (ui.uiMode).

Configuration

Control MCP behavior during install or upgrade:

Helm
CLI

ui:
  mcp:
    enabled: true
  mcpAccessMode: read-only   # or read-write

helm upgrade odigos odigos/odigos \
  --namespace odigos-system \
  --reuse-values \
  --set ui.mcpAccessMode=read-write

odigos install --set ui.mcpAccessMode=read-write

Set ui.mcp.enabled: false to disable the /mcp endpoint entirely.

What you can do

Odigos supports a growing list of both low-level and high-level MCP tools to confidently and securely access your clusters. They are grouped by domain — common starting points:

Goal	Tools to try
Is Odigos healthy?	`describe_odigos`, `get_gateway_info`, `get_odiglet_info`
What is instrumented?	`list_sources`, `list_workloads_in_namespace`
Why is a workload not sending data?	`describe_source`, `get_runtime_detection`, `get_instrumentation_health`
How much data is flowing?	`get_overview_metrics`, `get_service_map`
Configure a backend	`list_destination_types`, `get_destination_schema`, `create_destination`
Tune sampling	`get_sampling`, `create_sampling_group`, `create_noisy_operation_rule`
Profile a hot path	`enable_source_profiling`, `get_source_hot_functions`, `add_custom_instrumentation`
Collect support bundle	`collect_diagnose_bundle`

Write tools support dry_run: true (the default) so agents can preview changes before applying them. When the server is in read-only mode, write tools are not executed even with dry_run: false.

Tool responses include context and next_steps hints to help agents chain calls without manual guidance.

Audit logs

Every MCP tool call is audit-logged by the Odigos UI pod. The audit middleware records the tool name, outcome, and duration on every tools/call — including calls blocked in read-only mode.

Field	Description
`tool`	MCP tool name (for example `describe_odigos`, `create_destination`)
`outcome`	`ok` — succeeded · `tool_error` — handler returned an error result (includes writes rejected in read-only mode) · `error` — unexpected failure
`duration_ms`	Wall-clock time for the call, in milliseconds

Example log lines from the UI pod (kubectl logs -n odigos-system deploy/odigos-ui):

{"level":"info","ts":"2026-06-18T11:42:03.512Z","caller":"audit/audit.go:37","msg":"mcp tool call","component":"mcp","tool":"describe_odigos","outcome":"ok","duration_ms":38}
{"level":"info","ts":"2026-06-18T11:42:18.904Z","caller":"audit/audit.go:37","msg":"mcp tool call","component":"mcp","tool":"create_destination","outcome":"ok","duration_ms":214}
{"level":"info","ts":"2026-06-18T11:43:01.271Z","caller":"audit/audit.go:37","msg":"mcp tool call","component":"mcp","tool":"enable_source_profiling","outcome":"tool_error","duration_ms":1}

In the third line, enable_source_profiling was rejected because the server was in read-only mode — the call is still logged, but with outcome: tool_error instead of ok.

Security notes

The MCP endpoint is intended for in-cluster or trusted network use. There is no built-in authentication on /mcp in the current release — protect access at the network layer (port-forward, private ingress, VPN).
Prefer read-only mode for day-to-day agent use. Switch to read-write only when an operator is actively supervising changes.

What’s coming

Fine-grained access control via token — scoped, per-token MCP permissions, so you can grant each agent only the tools it needs instead of a single cluster-wide access mode.

Until then, the recommended approach is to issue a dedicated on-prem token per agent, keep the server in read-only mode for untrusted agents, and restrict who can reach /mcp at the network layer.

​Requirements

​Connect from Cursor

​Access modes

​Configuration

​What you can do

​Audit logs

​Security notes

​What’s coming

Requirements

Connect from Cursor

Access modes

Configuration

What you can do

Audit logs

Security notes

What’s coming