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
mcpability that both MCP endpoints require. - A token made in the dashboard expires after 90 days.
create-mcp-token-toolacceptsexpires_in_daysfrom 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:/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:
~/.zshrc, ~/.bashrc, etc.):
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):
${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, themcp-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-toolreturns the issue with itssubtype,group_hashandthreshold_ms, its comments and activity, andrecent_occurrences. For an exception issue those are exception occurrences with theirtrace_id. For a performance issue they are the executions that ran at or overthreshold_ms, each withtrace_id,duration_msand the ids you need to open it (attempt_idfor jobs, method and URL for routes and outgoing requests).get-issue-occurrences-toolreturns counts only: a time series, a per-environment breakdown, the total and unique users. Take trace ids fromget-issue-tool. For a scheduled-task performance issue,unique_usersisnull, because scheduled tasks record no user.update-issue-status-tool,bulk-update-issues-toolandadd-issue-comment-toolneed 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 getsThis action requires admin role.environmentfilters the results on every tool that takes it, andleveldoes onlist-logs-tool.time_rangetakes1h,6h,24h,7d,14dor30d, and defaults to24h. For a custom range, passfrom(ISO 8601) and optionallyto, which defaults to now. Passingfromselects the custom range on its own.towithoutfromis refused, and so is a presettime_rangetogether withfromorto.- The telemetry list tools (the
list-*-toolentries from Requests to Users in the table above) takepageandper_page.per_pageis 1 to 100 and defaults to 50. Onlist-requests-toolit sets the number of routes per page.list-route-requests-tooltakescursorinstead ofpage. list-route-requests-toollists one route’s individual requests, newest first, like the request table on the route page. Takegroup_hashfrom a route inlist-requests-tool.statuskeeps4xx,5xxorsuccessrequests,durationkeeps requests at or over the route’savg,p50,p95orp99, andsearchkeeps URLs containing the text. Each row has the request’strace_id,timestamp,method,url,status_codeandduration_ms. For the next page, pass the reply’snext_cursorascursor.get-request-toolopens one request bytrace_id, with the queries, exceptions, jobs, logs and outgoing requests of the same trace.request.payloadis the captured request payload andrequest.response_bodythe captured response body. Each is empty ornullwhen nothing was captured. On its own, Nightwatch records a payload only for a 500 response withNIGHTWATCH_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-toolreturns the user’s card. Passfilterto also get that user’s activity of one type, paged withpageandper_page:requests(the routes they called, with counts),jobs(job classes, with counts),exceptions(grouped by fingerprint) orlogs(newest first). The activity comes back next to the card, under the filter’s name.user_idmust be one user’s id:__guest__and__authenticated__are refused.list-alert-channels-toolmasks 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-toolreturns the new channel’sid. Its description lists the config each type needs.config.notify_eventspicks the events the channel receives (see Alert channels). Leaving it out sends every event, and an empty list sends none.update-alert-channel-toolkeeps the stored name when you leavenameout and merges the config keys you pass over the stored config. Set a key tonullto clear it. Sending a masked value back unchanged keeps the stored secret, and any other value replaces it. Changing an email channel’shostorportneeds thepasswordsent again.toggle-alert-channel-toolsets the state you pass inenabled. 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-toolsends 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 repliesToo many attempts. Try again in N seconds.destroy-data-toolstarts a deletion in the background and returns its id. Runpreview-deletion-toolfirst. If the preview reportsfilters_ignoredfor a table, the deletion needsacknowledge_ignored_filters: true, because those filters don’t narrow that table. With auser_idfilter, the preview also returnsuser_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-tooltakes asettingsobject. The keys it accepts areauto_resolve_days,alert_mute_until,slow_request_default_ms,slow_job_default_ms,slow_command_default_msandslow_query_default_ms.update-app-toolneedsdb_passwordto changedb_host,db_port,db_databaseordb_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 emptydb_passwordgetsdb_password cannot be empty. Omit it to keep the current password.regenerate-app-token-toolneeds the owner or admin role on the app’s team, as in the dashboard.create-team-invitation-toolrequiresemails(1 to 100 addresses), and only those addresses can accept the link. It expires after 7 days unless you passexpires_in_days(1 to 365). It’s refused when the invitations would take the team past its member limit.accept-team-invitation-toolfollows 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: amessage, thejoinedandskippedlists, andteam_idfor a team invitation.list-team-invitations-toollists the same pending links as the dashboard, including links that never expire and links that cover several teams, each with itsemails.
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: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:
bulk-update-issues-tool call changes both statuses, writes activity rows marked as MCP, and fires the configured alert channels.
Provision a new environment:
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
The client says the server failed to connect
The client says the server failed to connect
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.
A tool call fails with 'Tool not found'
A tool call fails with 'Tool not found'
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.Calls fail with a plan or feature error
Calls fail with a plan or feature error
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.A tool returns 'This action requires admin role.'
A tool returns 'This action requires admin role.'
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.
Tenant calls return 'App not found'
Tenant calls return 'App not found'
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>/…).A destructive tool returned a 'refusing to X' error
A destructive tool returned a 'refusing to X' error
Destructive tools require
confirm: "YES" (exact string, uppercase, no punctuation). This is deliberate: it stops a misread prompt from wiping an app.Mutating calls succeed but the dashboard is stale
Mutating calls succeed but the dashboard is stale
Tools clear the app’s API cache, so the dashboard shows the change on its next refresh. If it lingers, reload the browser tab.
How do I tell MCP edits from human ones?
How do I tell MCP edits from human ones?
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.