MCP Server

Updated on Aug 14, 2026

Overview

The Progress Observability MCP server exposes observation and evaluation data to AI clients. It is a remote, read-only server. Use the production endpoint at https://mcp.observability.progress.com/mcp and authenticate each request with an MCP API key.

Access is controlled by key scope, so each key can expose a different set of tools.

Data access through MCP is limited to observations from the last 72 hours. (This is the MCP access window, not how long the platform retains your data.)

Prerequisites

Before configuring your client, make sure you have:

• A paid Progress Observability plan (MCP is available only on paid plans).
• A generated MCP API key in Progress Observability.

The raw API key is shown only once when created. Save it securely.

Create an MCP API Key in Progress Observability

Go to API Keys → MCP API Keys and create a key with:

• Name/Description
• Expiration: 7, 30, 60, or 90 days
• Scope:
  • Metadata only for standard observability queries
  • With content when you need prompt/completion fields

You can later Revoke or Delete keys from the same page.

Warning: Trace data may contain untrusted LLM-generated content, including prompt-injection attacks and other adversarial instructions. API keys with content access permit AI assistants and applications to retrieve and process raw prompts and completions. By enabling content access and creating this API key, you acknowledge that trace content may contain malicious or misleading instructions and agree that such content must be treated solely as data, not as instructions for the AI system consuming it.

Client Configuration Reference (Codex CLI, GitHub Copilot, Claude Code, Cursor)

Use the production endpoint:

• https://mcp.observability.progress.com/mcp

Use environment variables for secrets whenever possible. Do not commit raw keys.

1. Codex CLI (and ChatGPT Desktop / Codex IDE extension)

Configuration files:

• User scope: ~/.codex/config.toml
• Project scope: .codex/config.toml

Example (.codex/config.toml):

toml

[mcp_servers.ObservabilityMCP]
enabled = true
url = "https://mcp.observability.progress.com/mcp"
env_http_headers = { "X-Api-Key" = "OBSERVABILITY_MCP_API_KEY" }
http_headers = { "User-Agent" = "Codex-CLI/0.144.0" }

Notes:

• url must be a plain URL string (no markdown links).
• Use env_http_headers when the API key is stored in an environment variable.
• If the API key is hardcoded in the config, it must be set in http_headers.
• Keep http_headers for non-sensitive headers when possible.

2. GitHub Copilot (via VS Code: Chat and CLI)

Configuration file: .vscode/mcp.json

GitHub Copilot Chat example:

json

{
	"servers": {
		"ObservabilityMCP": {
			"type": "http",
			"url": "https://mcp.observability.progress.com/mcp",
			"headers": {
				"X-Api-Key": "${input:observability-api-key}"
			}
		}
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "observability-api-key",
			"description": "Progress Observability MCP API key",
			"password": true
		}
	]
}

GitHub Copilot CLI example:

json

{
	"mcpServers": {
		"ObservabilityMCP": {
			"type": "http",
			"url": "https://mcp.observability.progress.com/mcp",
			"headers": {
				"X-Api-Key": "${input:observability-api-key}"
			}
		}
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "observability-api-key",
			"description": "Progress Observability MCP API key",
			"password": true
		}
	]
}

Note: Use inputs for secrets, or environment variables via variable interpolation.

3. Claude Code

Configuration files:

• User/local scope: ~/.claude.json
• Project/shared scope: .mcp.json

Example (.mcp.json):

json

{
	"mcpServers": {
		"ObservabilityMCP": {
			"type": "http",
			"url": "https://mcp.observability.progress.com/mcp",
			"headers": {
				"X-Api-Key": "${OBSERVABILITY_MCP_API_KEY}"
			}
		}
	}
}

4. Cursor

Configuration files:

• Project scope: .cursor/mcp.json
• Global scope: ~/.cursor/mcp.json

Example (.cursor/mcp.json):

json

{
	"mcpServers": {
		"ObservabilityMCP": {
			"url": "https://mcp.observability.progress.com/mcp",
			"headers": {
				"X-Api-Key": "${env:OBSERVABILITY_MCP_API_KEY}"
			}
		}
	}
}

Scope-to-Tool Mapping

There are 9 tools total. Both scopes let you list observations, evaluation tasks, scores, usage, and cost data. The difference is in detail endpoints: Metadata only exposes 7 tools with metadata-only details, while With content exposes all 9 tools including details that can include prompt and completion content.

Scope: Metadata only

• list_observations
• get_observation_details
• list_evaluation_tasks
• get_evaluation_task
• get_evaluation_scores
• get_usage_summary
• get_cost_breakdown

Scope: With content

• list_observations
• get_observation_details
• get_observation_details_with_content
• list_evaluation_tasks
• get_evaluation_task
• get_evaluation_task_with_content
• get_evaluation_scores
• get_usage_summary
• get_cost_breakdown

Available Tools and Descriptions

Tool	Description
list_observations	Search observations in a time window. Supports type=traces, spans, or evaluations, plus status, tags, service_name, pagination, and limit.
get_observation_details	Return metadata-only details for observation IDs (no raw attributes, no prompt/completion content). Optional child-span expansion.
get_observation_details_with_content	Return observation details including full span attributes content (which may contain prompt/completion text). Optional child-span expansion. Content-read scope required.
list_evaluation_tasks	List evaluation task definitions available to the tenant.
get_evaluation_task	Return metadata for specific evaluation task IDs (no prompt/scoring_prompt content).
get_evaluation_task_with_content	Return evaluation task definitions including prompt and scoring_prompt content. Content-read scope required.
get_evaluation_scores	Return evaluation scores for one evaluation task, with optional time filters, pagination, and limit.
get_usage_summary	Return current billing-period usage, quota, and remaining capacity.
get_cost_breakdown	Return USD cost attribution for a required date range, grouped by model, application, day, or all.

Tool Input Contracts (Required vs Optional)

This version reflects the current implementation.

Tool	Required inputs	Optional inputs
list_observations	none	start_time, end_time, cursor, type, status, tags, service_name, limit
get_observation_details	observation_ids[]	include_children, max_depth
get_observation_details_with_content	observation_ids[]	include_children, max_depth
list_evaluation_tasks	none	none
get_evaluation_task	evaluation_ids[]	none
get_evaluation_task_with_content	evaluation_ids[]	none
get_evaluation_scores	task_id	limit, cursor, start_time, end_time
get_usage_summary	none	none
get_cost_breakdown	start_date, end_date	group_by (default: all)

Guardrails and Limits

• list_observations

  • If no time range is provided, queries default to the last 24 hours.
  • Each request can cover at most 72 hours of data.
  • The default is 20 results. You can set limit from 1 to 100
  • Observation filtering supports type values traces, spans, and evaluations.

• get_observation_details

  • Detail lookup accepts between 1 and 10 observation_ids per request.
  • Data access is limited to observations from the last 72 hours.
  • Responses are metadata-only and omit raw span/resource attributes and prompt/completion content.
  • Child expansion depth is supported from 1 to 10 when include_children=true.

• get_observation_details_with_content

  • Content-inclusive lookup accepts between 1 and 3 observation_ids per request.
  • Data access is limited to observations from the last 72 hours.
  • Child expansion depth is supported from 1 to 10 when include_children=true.
  • Responses are capped at 1 MB.
  • Returned payloads include safety metadata and field-level tagged content classifications.

• get_evaluation_task

  • Accepts between 1 and 10 evaluation_ids per request.
  • Responses are metadata-only and do not include prompt or scoring_prompt content.

• get_evaluation_task_with_content

  • Content-inclusive task lookup accepts between 1 and 3 evaluation_ids per request.
  • prompt and scoring_prompt fields are truncated to 32 KB each.
  • Responses are capped at 1 MB.
  • Returned payloads include safety metadata and field-level tagged content classifications.

• get_evaluation_scores

  • Score retrieval is scoped to exactly one task_id per request.
  • If no time range is provided, scores default to the last 24 hours.
  • Data access is limited to observations from the last 72 hours.
  • The default is 20 results. You can set limit from 1 to 100

Rate Limits

MCP tool calls are rate-limited per API key/client, per tool, in a 1-minute window.

Tool category	Default limit
Metadata tools	60 permits per minute
Content tools	10 permits per minute

Additional notes:

• Multi-ID tools consume permits per requested ID (for example observation_ids or evaluation_ids count).
• If a limit is exceeded, the tool returns a structured rate-limit error with retryAfterSeconds so clients can back off and retry.

Common Errors

Authentication

• Authentication failed: your MCP API key is missing, invalid, or has expired. Please check your MCP API key configuration.
• MCP access is not available on the Free plan. Please upgrade to use MCP features.

Time-window violations

• list_observations — time window too large: Time range too large: hours requested, maximum is 72 hours. Use a smaller window or split into multiple queries.
• get_evaluation_scores — start time too old: start_time must be within the last 72 hours relative to now.
• get_observation_details / get_observation_details_with_content — span too old: Span is older than 72 hours. Access is restricted to data from the last 72 hours.

Security Considerations

MCP protections reduce risk, but they do not eliminate it.

Implemented mitigations:

• Safety labels on content responses: content-enabled tools include safety labels so AI clients can recognize risky content and treat it as data, not instructions.
• Content access is opt-in: only keys created with With content can call content-enabled tools.
• Safer default mode: metadata-only tools do not return raw prompt/completion text.
• Explicit consent: when you create a With content key, you must acknowledge the risk warning before the key can be created.

Quick Connectivity Test

bash

curl -s https://mcp.observability.progress.com/mcp \
	-H "Content-Type: application/json" \
	-H "Accept: application/json, text/event-stream" \
	-H "X-Api-Key: <YOUR_MCP_KEY>" \
	-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Expected result: tool list matching your key scope.

See Also

• Introduction to Progress Observability Platform
• Get started with setup and first traces
• Understand traces, evaluations, and costs
• Manage organizations, roles, and plans
• Install agent skills for instrumentation, triage, and cost reporting
• Datasets & Experiments