Skip to main content
NightOwl ships two remote MCP servers so AI coding assistants can work with the same data and settings as the dashboard: browse telemetry, triage issues, provision apps, manage teams and configure alert channels. MCP is available on the Team and Agency plans. Issue changes and comments made through MCP are stored with actor_type=mcp, and the issue page marks them with an MCP badge, so you can tell them apart from edits made in the dashboard.

1. Generate a personal access token

Sign in to the dashboard, open the account menu (your name at the bottom of an app’s sidebar), choose Account, then Tokens in the left rail. In the MCP Tokens card, enter a label you’ll recognise (for example “Laptop, Claude Code”) and click Generate. The raw token is shown once, so copy it immediately. Afterwards the card shows only the label, when it was created and when it was last used.
  • Tokens belong to your user, reach the same apps your account can open with the same role on each, and carry the mcp ability that both MCP endpoints require.
  • A token made in the dashboard expires after 90 days. create-mcp-token-tool accepts expires_in_days from 1 to 365.
  • Each user can hold up to 20 MCP tokens.
  • Revoking a token blocks every client that uses it straight away.
Creating a token needs a Team or Agency plan on your own account. The per-app server also checks the plan of the team that owns the app, so a token works on an app only while that team’s owner is on Team or Agency.

2. The two servers

NightOwl exposes two MCP endpoints. You’ll usually register both. One token works on both. The platform server has 25 tools and the tenant server has 51.

3. Connect your client

Claude Code

Register both servers:
Run /mcp in Claude Code to verify both servers connected.

Codex

Codex reads MCP servers from ~/.codex/config.toml and resolves the bearer token from an environment variable. Edit the config:
Then export the token in your shell profile (~/.zshrc, ~/.bashrc, etc.):
Reload the shell (source ~/.zshrc) so Codex picks up the variable. Both servers can share the same env var, or use distinct ones if you’d rather scope tokens per server. If you’d rather not edit config.toml by hand, the same registration works via the CLI (token must already be exported):

Cursor

Cursor speaks bearer-token HTTP MCP natively. Add to .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global):
The ${env:NIGHTOWL_MCP_TOKEN} reference keeps the raw token out of the file. Export it from your shell profile. Cursor reloads the file when you save it.

Windsurf, Zed, and other stdio-only clients (via mcp-remote)

For clients that don’t yet support remote HTTP MCP, the mcp-remote shim proxies a remote server as stdio:
Self-hosted NightOwl? Replace https://api.usenightowl.com with your own API URL. The paths are identical.

4. What’s available

Tool names are the tool’s class name in kebab case, ending in -tool (ListIssuesTool is list-issues-tool). Clients must call the exact name, so a near miss such as list_issues or get-issue fails with “Tool not found”.

Platform server (/mcp/platform)

Tenant server (/mcp/<app-id>)

⚠ = destructive. These tools refuse to run without an explicit confirm: "YES" argument.

Things worth knowing about specific tools

  • get-issue-tool returns the issue with its subtype, group_hash and threshold_ms, its comments and activity, and recent_occurrences. For an exception issue those are exception occurrences with their trace_id. For a performance issue they are the executions that ran at or over threshold_ms, each with trace_id, duration_ms and the ids you need to open it (attempt_id for jobs, method and URL for routes and outgoing requests).
  • get-issue-occurrences-tool returns counts only: a time series, a per-environment breakdown, the total and unique users. Take trace ids from get-issue-tool. For a scheduled-task performance issue, unique_users is null, because scheduled tasks record no user.
  • update-issue-status-tool, bulk-update-issues-tool and add-issue-comment-tool need the owner or admin role on the app, as in the dashboard. So do the tools that change alert channels, settings, thresholds or data. A member’s token gets This action requires admin role.
  • environment filters the results on every tool that takes it, and level does on list-logs-tool.
  • time_range takes 1h, 6h, 24h, 7d, 14d or 30d, and defaults to 24h. For a custom range, pass from (ISO 8601) and optionally to, which defaults to now. Passing from selects the custom range on its own. to without from is refused, and so is a preset time_range together with from or to.
  • The telemetry list tools (the list-*-tool entries from Requests to Users in the table above) take page and per_page. per_page is 1 to 100 and defaults to 50. On list-requests-tool it sets the number of routes per page. list-route-requests-tool takes cursor instead of page.
  • list-route-requests-tool lists one route’s individual requests, newest first, like the request table on the route page. Take group_hash from a route in list-requests-tool. status keeps 4xx, 5xx or success requests, duration keeps requests at or over the route’s avg, p50, p95 or p99, and search keeps URLs containing the text. Each row has the request’s trace_id, timestamp, method, url, status_code and duration_ms. For the next page, pass the reply’s next_cursor as cursor.
  • get-request-tool opens one request by trace_id, with the queries, exceptions, jobs, logs and outgoing requests of the same trace. request.payload is the captured request payload and request.response_body the captured response body. Each is empty or null when nothing was captured. On its own, Nightwatch records a payload only for a 500 response with NIGHTWATCH_CAPTURE_REQUEST_PAYLOAD=true, and never a response body. To capture payloads for other statuses, or response bodies, see Request payloads and response bodies.
  • get-user-tool returns the user’s card. Pass filter to also get that user’s activity of one type, paged with page and per_page: requests (the routes they called, with counts), jobs (job classes, with counts), exceptions (grouped by fingerprint) or logs (newest first). The activity comes back next to the card, under the filter’s name. user_id must be one user’s id: __guest__ and __authenticated__ are refused.
  • list-alert-channels-tool masks secrets. An SMTP password or webhook signing secret reads ••••••••, and a Slack, Discord or webhook URL keeps only its scheme and host (https://hooks.slack.com/••••••••).
  • create-alert-channel-tool returns the new channel’s id. Its description lists the config each type needs. config.notify_events picks the events the channel receives (see Alert channels). Leaving it out sends every event, and an empty list sends none.
  • update-alert-channel-tool keeps the stored name when you leave name out and merges the config keys you pass over the stored config. Set a key to null to clear it. Sending a masked value back unchanged keeps the stored secret, and any other value replaces it. Changing an email channel’s host or port needs the password sent again.
  • toggle-alert-channel-tool sets the state you pass in enabled. It refuses to enable a channel that can’t send yet (no webhook URL, no SMTP host, an SMTP username without its password, or an email channel with no recipients). It also refuses to enable an email channel with a recipient who isn’t a member of the app’s team.
  • test-alert-channel-tool sends from NightOwl’s servers, like the dashboard’s Send test, so it can’t reach a private SMTP host. See Testing a channel. It shares the Send test limit: 5 tests a minute and 30 an hour per user, counted together with the dashboard. The tools that create, update, delete or toggle a channel share the dashboard’s limit on those changes, 60 a minute per user. Over a limit, a tool replies Too many attempts. Try again in N seconds.
  • destroy-data-tool starts a deletion in the background and returns its id. Run preview-deletion-tool first. If the preview reports filters_ignored for a table, the deletion needs acknowledge_ignored_filters: true, because those filters don’t narrow that table. With a user_id filter, the preview also returns user_identity, which says whether that user’s stored name and email would be removed (see Deleting data for one user). Like the dashboard, it needs the granular clear feature on the plan of the app’s team owner, and each user can start three deletions per hour, counted together with the dashboard.
  • update-settings-tool takes a settings object. The keys it accepts are auto_resolve_days, alert_mute_until, slow_request_default_ms, slow_job_default_ms, slow_command_default_ms and slow_query_default_ms.
  • update-app-tool needs db_password to change db_host, db_port, db_database or db_username, because NightOwl never sends a saved password to a connection it wasn’t saved for (see Test Connection). A field you pass can’t be empty. An empty db_password gets db_password cannot be empty. Omit it to keep the current password.
  • regenerate-app-token-tool needs the owner or admin role on the app’s team, as in the dashboard.
  • create-team-invitation-tool requires emails (1 to 100 addresses), and only those addresses can accept the link. It expires after 7 days unless you pass expires_in_days (1 to 365). It’s refused when the invitations would take the team past its member limit.
  • accept-team-invitation-tool follows the dashboard’s rules: the link must be for your email address, and an app invitation gives you only the invited apps. It returns the dashboard’s result: a message, the joined and skipped lists, and team_id for a team invitation.
  • list-team-invitations-tool lists the same pending links as the dashboard, including links that never expire and links that cover several teams, each with its emails.
The Copy AI prompt button on an exception writes a debugging brief for your assistant that uses these tools by their real names. On a request, job attempt, command or scheduled task page, the brief includes the ids that run’s tool needs (get-request-tool, get-job-attempt-tool, get-command-attempt-tool or get-scheduled-task-attempt-tool). On an issue or exception group page, it tells the assistant how to find the run first.

5. Safety model

Scoped tokens

A token reaches only the apps its user can open in the dashboard, with the same role on each. A member limited to some apps reaches only those, on both servers. The app-id in the URL is checked on every call.

Audit trail

Issue changes and comments made through MCP are stored with actor_type=mcp and actor_meta holding the token label, token id and the client’s user agent. The issue page shows an MCP badge with the token label next to the token owner’s name.

Instant revoke

Revoking a token from Account → Tokens blocks every client using it, with no redeploy or restart.

Confirmation gates

delete-app-tool, regenerate-app-token-tool and destroy-data-tool refuse to run without confirm: "YES". preview-deletion-tool only counts rows and never deletes.

Same alerts as the dashboard

Status changes made through MCP fire the same Slack, Discord, email and webhook channels as a change made in the dashboard.

Self-revoke protection

delete-mcp-token-tool refuses to delete the token making the call. Revoke that one from the dashboard instead.

6. Example workflows

Once both servers are connected, a single prompt can span NightOwl data, your codebase, and team operations:
The assistant calls list-issues-tool on the tenant server, then get-issue-tool on each result, then runs git log locally to compare against recent changes. Close the loop:
One bulk-update-issues-tool call changes both statuses, writes activity rows marked as MCP, and fires the configured alert channels. Provision a new environment:
Two platform calls (test-app-connection-tool, create-app-tool). The agent token comes back once in the response. Retention cleanup:
preview-deletion-tool returns per-table row counts. The assistant summarises them and calls destroy-data-tool (with confirm: "YES") only after you approve.

Troubleshooting

Most common cause: a stale, expired or mistyped token. Generate a new one in the dashboard and re-add the MCP server. Some clients cache server metadata, so remove and re-add the server entry to force a refresh.
The name doesn’t match a registered tool. Names are kebab case and end in -tool (list-issues-tool, not list_issues or list-issues). Ask the client to list the server’s tools, or check the tables above.
MCP needs the Team or Agency plan: on your own account to create a token and use the platform server, and on the account that owns the app’s team to use its tenant server. The agent health tools also need Agent Health, and destroy-data-tool the granular clear feature, on the team owner’s plan. While a team owner’s subscription has lapsed, the tools for that team and its apps return the same message as the dashboard.
Your role on that app is Member. Changing issues, alert channels, settings, thresholds or data needs the owner or admin role on the team, or Admin access to that app. Ask a team owner or admin to change your access on the Teams page.
The app-id in the URL must be an app your account can open. A member limited to some apps gets this error on the team’s other apps. Copy the ID from the app’s URL in the dashboard (/dashboard/<app-id>/…).
Destructive tools require confirm: "YES" (exact string, uppercase, no punctuation). This is deliberate: it stops a misread prompt from wiping an app.
Tools clear the app’s API cache, so the dashboard shows the change on its next refresh. If it lingers, reload the browser tab.
On the issue page, comments and activity written through MCP carry an MCP badge with the token’s label. The name shown is the token’s owner. get-issue-tool returns actor_type on each comment and activity row.