# Observer MCP Server

WSO2 Agent Manager (AMP) ships a second Model Context Protocol (MCP) server — `am-obs-mcp` — hosted by `agent-manager-observer`. Where the [main MCP server](/agent-manager/docs/next/reference/mcp-server/.md) covers the agent lifecycle (projects, agents, builds, deployments), this server lets MCP-capable AI assistants inspect a deployed agent's runtime logs, build logs, metrics, and traces.

## Overview[​](#overview "Direct link to Overview")

The observer MCP server is exposed by `agent-manager-observer` at the `/mcp` path on the observer's public URL. It speaks MCP over Streamable HTTP and is protected by the same bearer-token authentication as the observer's REST API (`/api/v1/logs`, `/api/v1/metrics`, `/api/v1/build-logs`, `/api/v1/traces`) — an access token obtained through the same OAuth 2.0 Authorization Code + PKCE flow used for `agent-manager-service`, against the bundled Thunder identity provider.

Unlike the main MCP server's tools, every `am-obs-mcp` tool call is scoped by an explicit, required `organization` parameter (the caller states which organization it wants data for) rather than deriving it from token claims. The one exception is `get_span_details`, which looks a span up by trace ID and span ID alone.

## Available Tools[​](#available-tools "Direct link to Available Tools")

The observer MCP server provides **7 tools** organized into two toolsets: Observability (runtime logs, build logs, metrics) and Tracing (traces and spans).

**Observability Toolset (3 tools)**

#### `get_runtime_logs`[​](#get_runtime_logs "Direct link to get_runtime_logs")

Return runtime logs for an agent — the application logs emitted by a deployed agent — filterable by time window, log level, sort order, or text search.

| Parameter       | Required | Description                                                                                                                 |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `organization`  | Yes      | Organization name.                                                                                                          |
| `project`       | Yes      | Project name.                                                                                                               |
| `agent`         | Yes      | Agent name.                                                                                                                 |
| `environment`   | Yes      | Environment name.                                                                                                           |
| `start_time`    | No       | Start time in RFC3339 format. Defaults to 24h before `end_time`/now. Cannot be in the future. Window cannot exceed 14 days. |
| `end_time`      | No       | End time in RFC3339 format. Defaults to now.                                                                                |
| `limit`         | No       | Max number of log entries to return. Must be positive; requests over the 10000 cap are rejected (not clamped).              |
| `sort_order`    | No       | `asc` or `desc`. Defaults to the upstream route's default when omitted.                                                     |
| `log_levels`    | No       | Filter to one or more of `INFO`, `DEBUG`, `WARN`, `ERROR` (case-insensitive).                                               |
| `search_phrase` | No       | Free-text search phrase to match against log content.                                                                       |

#### `get_build_logs`[​](#get_build_logs "Direct link to get_build_logs")

Return logs for a specific build of an internal agent — the step-by-step output produced while packaging the agent source into a runnable image.

| Parameter      | Required | Description                          |
| -------------- | -------- | ------------------------------------ |
| `organization` | Yes      | Organization name.                   |
| `build_name`   | Yes      | Name of the build to fetch logs for. |

#### `get_metrics`[​](#get_metrics "Direct link to get_metrics")

Return CPU and memory usage, request and limit metrics for an agent over a selected time range — runtime resource consumption for a deployment in a specific environment.

| Parameter      | Required | Description                                                                                        |
| -------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `organization` | Yes      | Organization name.                                                                                 |
| `project`      | Yes      | Project name.                                                                                      |
| `agent`        | Yes      | Agent name.                                                                                        |
| `environment`  | Yes      | Environment name.                                                                                  |
| `start_time`   | No       | Start time in RFC3339 format. Defaults to 24h before `end_time`/now. Window cannot exceed 14 days. |
| `end_time`     | No       | End time in RFC3339 format. Defaults to now.                                                       |

**Tracing Toolset (4 tools)**

#### `list_traces`[​](#list_traces "Direct link to list_traces")

Returns a summary view of recent traces for an agent within a time window. A trace is a single end-to-end execution record for an agent request.

| Parameter      | Required | Description                                                                                        |
| -------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `organization` | Yes      | Organization name.                                                                                 |
| `project`      | Yes      | Project name.                                                                                      |
| `agent`        | Yes      | Agent name.                                                                                        |
| `environment`  | Yes      | Environment name.                                                                                  |
| `start_time`   | No       | Start time in RFC3339 format. Defaults to 24h before `end_time`/now. Window cannot exceed 30 days. |
| `end_time`     | No       | End time in RFC3339 format. Defaults to now.                                                       |
| `limit`        | No       | Max number of traces to return. Defaults to 10; values over 1000 are clamped down to 1000.         |
| `sort_order`   | No       | `asc` (oldest first) or `desc` (newest first). Defaults to `desc`.                                 |

#### `get_traces`[​](#get_traces "Direct link to get_traces")

Returns the traces for an agent including full span details within a time window. A trace contains spans that record the internal steps of an execution.

Takes the same parameters as `list_traces`, but defaults `limit` to 100 and clamps values over 1000 down to 1000.

#### `get_trace_details`[​](#get_trace_details "Direct link to get_trace_details")

Return the metadata plus its full span list for one trace.

| Parameter      | Required | Description                                                                                        |
| -------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `organization` | Yes      | Organization name.                                                                                 |
| `project`      | Yes      | Project name.                                                                                      |
| `agent`        | Yes      | Agent name.                                                                                        |
| `environment`  | Yes      | Environment name.                                                                                  |
| `trace_id`     | Yes      | Trace ID to fetch.                                                                                 |
| `start_time`   | No       | Start time in RFC3339 format. Defaults to 24h before `end_time`/now. Window cannot exceed 30 days. |
| `end_time`     | No       | End time in RFC3339 format. Defaults to now.                                                       |

There is no `limit` or `sort_order` input — the tool always requests the server's full per-request span cap in chronological (`asc`) order, since its job is "show me this trace" rather than a paginated span list.

#### `get_span_details`[​](#get_span_details "Direct link to get_span_details")

Return the execution details for a single span — a single step within a trace execution, such as an LLM call, tool invocation, or retriever lookup, including its timing, inputs, outputs, and attributes.

| Parameter  | Required | Description                   |
| ---------- | -------- | ----------------------------- |
| `trace_id` | Yes      | Trace ID containing the span. |
| `span_id`  | Yes      | Span ID to fetch.             |

`get_span_details` has no `organization` parameter: the underlying lookup is scoped by trace/span ID alone and never consults organization or namespace scoping.

## Finding the Observer MCP Server URL[​](#finding-the-observer-mcp-server-url "Direct link to Finding the Observer MCP Server URL")

The observer MCP server URL follows the public URL of `agent-manager-observer`:

```
<observer-public-url>/mcp
```

If you don't know the observer's public URL, `agent-manager-service` publishes it through its unauthenticated service-configuration discovery endpoint:

```
curl http://api.amp.localhost:8080/api/v1/config
```

```
{ "observerBaseUrl": "http://traces.amp.localhost:11080" }
```

Append `/mcp` to the returned `observerBaseUrl` to get the full MCP server URL, e.g.:

```
http://traces.amp.localhost:11080/mcp
```

If you have changed the observer's public URL from the default, substitute that value.

## Configuring AI Assistants[​](#configuring-ai-assistants "Direct link to Configuring AI Assistants")

The observer MCP server is authenticated the same way as the [main MCP server](/agent-manager/docs/next/reference/mcp-server/.md#default-oauth-client) — the same pre-registered `am-mcp` OAuth client and pinned callback port `33418` apply, since both servers accept the same bearer token. Follow the [Configuring AI Assistants](/agent-manager/docs/next/reference/mcp-server/.md#configuring-ai-assistants) instructions there, substituting the observer MCP server URL for the `agent-manager-service` one, for example:

```
claude mcp add --transport http agent-manager-observer http://traces.amp.localhost:11080/mcp \
  --client-id am-mcp \
  --callback-port 33418
```

## Next Steps[​](#next-steps "Direct link to Next Steps")

* Try a few prompts in Claude Code, e.g. *"Show me the last 10 traces for agent X"*, *"Get the runtime logs for agent X in the dev environment"*, *"What are the CPU and memory metrics for agent X over the last hour?"*.
* See [MCP Server](/agent-manager/docs/next/reference/mcp-server/.md) for the agent-lifecycle tools (projects, agents, builds, deployments).