Skip to main content
NightOwl ships a remote MCP server so AI coding assistants can browse issues, read stack traces, and update statuses from your editor. Every AI-initiated change is logged in the issue activity timeline with actor_type=mcp, so human and AI edits stay visually distinct and a token can be revoked instantly.

​
1. Generate a personal access token

Sign in to the dashboard, open Account → Settings, and scroll to the MCP Tokens card. Give the token a memorable label (e.g. “Laptop — Claude Code”) and copy the token shown once in the modal. After that, only the label, creation date, and last-used timestamp are visible. Revoking a token from the same page blocks all clients using it immediately. Tokens are user-scoped and inherit your team membership. They have the mcp ability and can only be used against the MCP endpoint.

​
2. Connect your client

The endpoint is app-scoped: /api/mcp/<app-id>. Each client connection talks to exactly one NightOwl app. Copy the app ID from the Apps page in the dashboard.

​
Claude Code

claude mcp add --transport http nightowl \
  https://usenightowl.com/api/mcp/<app-id> \
  --header "Authorization: Bearer <token>"
Run /mcp in a Claude Code session to verify the server connected. The six tools should appear under the nightowl entry.

​
Codex

codex mcp add nightowl \
  --url https://usenightowl.com/api/mcp/<app-id> \
  --header "Authorization: Bearer <token>"

​
Cursor, Windsurf, Zed (via mcp-remote)

Bearer-token HTTP MCP isn’t native in these clients yet — use the mcp-remote shim to proxy the remote server as stdio. Add to .cursor/mcp.json (or the equivalent for Windsurf/Zed): 
{
  "mcpServers": {
    "nightowl": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://usenightowl.com/api/mcp/<app-id>",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}
Self-hosted NightOwl? Replace https://usenightowl.com with your own dashboard URL. The path (/api/mcp/<app-id>) is identical.

​
3. Available tools

All tools operate on the app ID in the URL — AI clients never need to pass app_id as an argument.
ToolPurpose
list_issuesFilter issues by type, status, environment, priority, assignee, or free-text search. Returns compact summaries.
get_issueFull issue detail: latest exception, stack trace, recent occurrences, comments, and activity timeline.
get_stack_traceParsed stack frames classified as app vs vendor. Optional trace_id for a specific occurrence.
get_issue_occurrencesTime-bucketed counts over 24h, 7d, or 30d. Includes breakdown by environment and unique users affected.
update_issue_statusChange status (open / resolved / ignored), priority, or assignee. Fires the same alert channels a human edit would.
add_issue_commentPost a markdown comment. Pass resolve: true to auto-resolve the issue in the same call.

​
4. Safety model

Scoped tokens

Tokens can only access apps where the owning user is a team member. The URL’s app-id is validated on every call.

Audit trail

Every mutating call writes an activity record with actor_type=mcp and actor_meta carrying the token label and client user-agent.

Instant revoke

Deleting a token from Account → Settings blocks all in-flight and future calls using it. No redeploy.

Webhook parity

Status changes made via MCP fire the same Slack, Discord, email, and webhook channels that a human edit would.

​
5. Example workflow

Once the server is connected, a single prompt can span NightOwl data and your codebase: 
> What are the top three open exceptions in production,
  and is any of them caused by code I changed in the last week?
The assistant calls list_issues with {status: "open", environment: "production", limit: 3}, then get_issue for each hit, then runs git log locally to cross-reference authorship — root cause in one turn. When you’ve fixed one, close the loop: 
> Mark issue #4812 as resolved and leave a comment explaining
  the null check in OrderService was the fix.
A single add_issue_comment call with resolve: true posts the comment, flips the status, and fires the configured alert channels — all attributed to MCP rather than to you directly.

​
Troubleshooting

The most common cause is a stale or mistyped token. Regenerate the token in the dashboard and re-run claude mcp add. Claude caches server metadata per workspace — run claude mcp remove nightowl first, then re-add.
The app-id in the URL must match an app your user account has team access to. Copy the ID directly from the Apps page — it’s the last segment of the app detail URL.
The tool calls flush the app cache, so the dashboard should refresh within its normal polling interval (30s for list pages, 10s for dashboards). If it lingers longer, hard-refresh the browser tab.
Check the activity filter — the timeline supports filtering by actor_type. MCP-authored actions share the timeline with human ones and are only hidden if you’ve filtered them out.