agensights-mcp

Model Context Protocol server for AgenSights — adds AI agent observability to your project via natural-language tool calls in any MCP-compatible host (Claude Code, Cursor, Codex, Gemini CLI, Claude Desktop, Kimi CLI, etc.).

Instead of reading SDK docs and copy-pasting init code, just tell your AI:

"instrument this agent with agensights"

The MCP handles project creation, API key generation, SDK install, code scaffolding, and verification — all behind one OAuth device-code login.

Install

Claude Code

claude mcp add agensights -- npx -y agensights-mcp

Cursor / Codex / Claude Desktop

Add to your MCP config:

{
  "mcpServers": {
    "agensights": {
      "command": "npx",
      "args": ["-y", "agensights-mcp"]
    }
  }
}

Tools (Phase 1)

| Tool | What it does | |------|--------------| | agensights_login | Device-code OAuth flow (no API keys in config). | | agensights_logout | Clear cached MCP session. | | agensights_create_project | Create or reuse a project. | | agensights_list_projects | Show projects in your org. | | agensights_create_api_key | Generate a project-scoped key. Plaintext returned once. | | agensights_install_sdk | Auto-detect Python/TS, run install, write .env. | | agensights_scaffold_tracing | Insert agensights.init() + @agensights.agent(...) on your agent's entry function. Diff-first; apply only on confirm. | | agensights_track_agent | Record a single LLM/tool/agent run directly via the ingest API. Lets the AI host log a run it just orchestrated without going through the SDK. | | agensights_verify_setup | Poll ingestion health to confirm events flow. |

Auth lifetime

Logging in is a one-time-per-week event:

• Access token — 15 min lifetime. Refreshed silently in the background; the user never sees this.
• Refresh token — 7 days lifetime, single-use rotating. Each refresh consumes the old one and issues a new one (replay-proof).
• What happens after 15 min — nothing visible. The MCP detects the access token is within 30 s of expiry on its next API call and exchanges the refresh token for a new pair before continuing.
• What happens after 7 days idle — the refresh fails, the cache is cleared, and the next tool call surfaces "Session expired. Run agensights_login again." The developer approves once more, then they're set for another week.

Security model

The MCP runs on the developer's machine and is invoked by an AI assistant that may itself be subject to prompt injection. The MCP defends against both an actively malicious model and a misbehaving one:

• No API keys in config. Auth happens via OAuth 2.0 device flow (RFC 8628). Tokens land in ~/.agensights/token.json (mode 0600) and are short-lived (15 min access, rotating refresh).
• MCP-scoped tokens cannot perform destructive actions. delete project, delete API key, cancel subscription, and other owner-only routes reject scope="mcp" JWTs server-side. Those still require a dashboard session.
• SSRF guard on AGENSIGHTS_API_URL. The configured URL must be HTTPS to a public host, or HTTP to localhost. Private IPv4/IPv6 ranges (10/8, 127/8, 169.254/16, 172.16/12, 192.168/16, fc/fd, fe80::, ::1) are blocked at startup.
• Workspace sandbox. File-write tools (install_sdk, scaffold_tracing) refuse to operate outside the directory the MCP was launched from, and refuse to touch .ssh, .aws, .gnupg, .kube, .docker, .npmrc, .pypirc, .netrc paths regardless of input.
• No shell interpolation. Package-manager invocations use spawnSync with a closed allowlist (npm/pnpm/yarn/pip/uv) and hardcoded argv. User-controlled strings are never spliced into a command line.
• Identifier validation. Function names passed to scaffold_tracing must match /^[A-Za-z_][A-Za-z0-9_]*$/. Project/key names use a conservative human-name regex.
• Token redaction in errors. All error messages returned to the AI pass through a redactor that masks bearer tokens and long opaque strings before display.
• Diff-first edits. scaffold_tracing returns a unified diff by default; the AI must explicitly call again with apply: true to write changes.

Auth

The MCP never accepts API keys via config. On first tool call it runs an OAuth 2.0 device authorization grant (RFC 8628):

1. MCP prints a verification URL + 8-character user code.
2. You open the URL in your browser, sign in to your dashboard, click Approve.
3. MCP receives a short-lived access token (15 min) + rotating refresh token, cached at ~/.agensights/token.json (mode 0600).

Environment

| Variable | Default | Purpose | |----------|---------|---------| | AGENSIGHTS_API_URL | https://api.agensights.com | Override for self-hosted deployments. |

Development

npm install
npm run build
node dist/index.js   # speaks MCP over stdio

License

MIT