Skip to main content
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.
1

Port-forward the UI

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

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.
3

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.
4

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).
ModeBehavior
read-only (default)Safe inspection only. Write requests are rejected.
read-writeMutating 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: 
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
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:
GoalTools 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 backendlist_destination_types, get_destination_schema, create_destination
Tune samplingget_sampling, create_sampling_group, create_noisy_operation_rule
Profile a hot pathenable_source_profiling, get_source_hot_functions, add_custom_instrumentation
Collect support bundlecollect_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.
FieldDescription
toolMCP tool name (for example describe_odigos, create_destination)
outcomeok — succeeded · tool_error — handler returned an error result (includes writes rejected in read-only mode) · error — unexpected failure
duration_msWall-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.