> ## Documentation Index
> Fetch the complete documentation index at: https://docs.odigos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Enterprise MCP Server

> Explore the MCP tools and MCP servers provided by Odigos — get insights and configure your cluster at your fingertips.

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.

<Steps>
  <Step title="Port-forward the UI">
    ```bash theme={null}
    kubectl port-forward -n odigos-system svc/ui 3000:3000
    ```
  </Step>

  <Step title="Add the MCP server in Cursor">
    Open **Cursor Settings → MCP** and add a server with a streamable HTTP URL:

    ```json theme={null}
    {
      "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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Ask your cluster a question">
    Query Odigos directly through MCP, for example:
    *"Which sources are unhealthy in the `default` namespace?"*
  </Step>
</Steps>

## 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](#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:

<Tabs>
  <Tab title="Helm">
    ```yaml theme={null}
    ui:
      mcp:
        enabled: true
      mcpAccessMode: read-only   # or read-write
    ```

    ```bash theme={null}
    helm upgrade odigos odigos/odigos \
      --namespace odigos-system \
      --reuse-values \
      --set ui.mcpAccessMode=read-write
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    odigos install --set ui.mcpAccessMode=read-write
    ```
  </Tab>
</Tabs>

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

<Info>
  Tool responses include `context` and `next_steps` hints to help agents chain
  calls without manual guidance.
</Info>

## 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`):

```json theme={null}
{"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.