Monitor usage and operations | MCP Stack Docs

After a server is published, the operational question changes from "does it generate?" to "can developers trust it in production?" MCP Stack surfaces the signals you need to debug MCP traffic and keep the runtime healthy.

Host observability flow

Operational views connect client traffic, Gateway decisions, runtime health, upstream calls, and quota pressure.

What to inspect first#

Use this order during an incident:

Server status and hosted MCP URL on the Hosting tab.
tools/list smoke result from the dashboard or CLI.
Gateway logs if OAuth or external clients are involved.
Runtime publish logs and deployment operations.
Upstream API status and credentials.
Usage, AI credits, and quota pressure.

Dashboard path#

Open the MCP server detail page.
On Hosting, confirm publish status, regional health, and the active MCP URL.
Run the built-in smoke test or open publish logs for the latest operation.
On Logs, filter request and tool-call history (paginated).
Open Gateways → select the profile → Logs when auth is involved.
Open Usage or Settings → Billing for org-level consumption and credit balance.

For agent-specific spend, open the agent Budget & Usage tab. See Agent budgets and usage.

CLI path#

BASH

mcpstack servers get support-api --json
mcpstack smoke tools-list support-api --json
mcpstack servers checks support-api --json
mcpstack logs stream support-api
mcpstack gateways logs gw_support
mcpstack operations list support-api --json
mcpstack agents usage ag_support --json

Use servers checks and smoke tools-list as release gates after config changes.

API path#

Read server logs (paginated):

HTTP

GET /api/v1/organizations/{orgId}/mcp-servers/{serverId}/logs?page=1&pageSize=50
Authorization: Bearer {token}

Run hosting checks and smoke tests:

HTTP

POST /api/v1/organizations/{orgId}/mcp-servers/{serverId}/hosting-checks
POST /api/v1/organizations/{orgId}/mcp-servers/{serverId}/mcp-smoke/tools-list

Read deployment state and operations:

HTTP

GET /api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment
GET /api/v1/organizations/{orgId}/mcp-servers/{serverId}/deployment-operations

Read Gateway logs:

HTTP

GET /api/v1/organizations/{orgId}/gateways/{gatewayId}/logs?page=1&pageSize=50

Read AI credit summary:

HTTP

GET /api/v1/organizations/{orgId}/ai-credits/summary

Request and tool-call logs#

Gateway and server logs help answer:

Which client or agent made the call?
Which MCP method was called?
Which tool was invoked?
Was auth required, connected, denied, or expired?
Did the runtime return a tool error?
Did the upstream API return a 4xx or 5xx?

Use logs to debug behavior before changing prompts. Many "agent bugs" are actually auth, schema, or upstream API errors.

Usage and plan limits#

Watch tool-call volume, response sizes, runtime errors, agent usage, hosted server count, and AI credit balance. Hosted runtimes have plan limits for max tool-call duration and request/response size.

See Billing and AI credits for purchases, ledger history, and hosted plan caps.

Smoke checks#

JSON

{
  "server": "support-api",
  "transport": "streamable-http",
  "status": "passed",
  "toolCount": 14
}

Run smoke checks after server creation, saved server changes, Gateway changes, and upstream auth changes.

Troubleshooting#

Symptom	What to check
Empty server logs	Confirm requests hit the correct MCP URL; check Gateway vs direct hosted URL.
Smoke passes but agent fails	Compare agent-attached server, Gateway grants, and tool instructions.
Sudden usage spike	Agent budget settings, embed traffic, external client volume.
Credits drop without code changes	Ledger debits for hosted agent usage; open Settings → Billing.

Quick answer#

When an agent can't use a tool, collect the server ID, timestamp, client or agent, tool name, and whether tools/list passes. Then compare Gateway logs, runtime logs, and upstream API responses for the same window.