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 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
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
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
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
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
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
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
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
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
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
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
The observer MCP server is authenticated the same way as the main MCP server — 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 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
- 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 for the agent-lifecycle tools (projects, agents, builds, deployments).