POC SE Tools — MCP (Claude Desktop)

Local stdio MCP server for Claude Desktop and other MCP clients. Calls your deployed poc-se-tools REST APIs with a personal MCP token from Settings.

Full setup guide: docs/MCP.md in the repo; signed-in users can also open /MCP.md in the web app (Settings → Claude Desktop).

Quick start (Claude Desktop — recommended)

No Node.js or JSON editing needed:

1. In poc-se-tools: Settings → Claude Desktop (MCP) → Generate token (copy once; expires after 90 days).
2. Click Download for Claude Desktop in the same section (poc-se-tools.mcpb).
3. Double-click the downloaded file and paste your token into the install dialog.
4. Turn it on — new extensions are installed disabled: Claude Desktop Settings → Extensions → POC SE Tools → switch on, then start a new chat.

Quick start (other MCP clients — manual)

1. Node.js 18+ on your machine.
2. In poc-se-tools: Settings → Claude Desktop (MCP) → Generate token (copy once).
3. Add to your client's MCP config (Claude Desktop: Settings → Developer → Edit Config):

{
  "mcpServers": {
    "poc-se-tools": {
      "command": "npx",
      "args": ["-y", "poc-se-tools-mcp@latest"],
      "env": {
        "POC_SE_TOOLS_BASE_URL": "https://poc.acmeorg.net",
        "POC_SE_TOOLS_MCP_TOKEN": "pst_mcp_..."
      }
    }
  }
}

4. Restart the client completely.

Tools (v0.7.0)

Read tools (any token):

| Tool | API | |------|-----| | get_profile | GET /api/user/profile (includes token scopes + update hint) | | list_poc_statuses | GET /api/pocs?meta=statuses | | list_pocs | GET /api/pocs (default: owner_me=true&display_status=ACTIVE&limit=25) | | list_poc_artifacts | GET /api/pocs/{id}/artifacts | | list_report_templates | GET /api/templates | | get_report_template | GET /api/templates/{id} (default: blank shell variant, logos by URL; variant: full, embed_logos: true to opt up) | | get_ai_report | artifacts?latest_ai_report=true (+ include_html, truncated to max_html_chars) | | get_api_report | artifacts?latest_api_report=true (+ include_html) | | get_poc_guide | artifacts?latest_guide=true (+ include_html) | | get_poc_summary | POC + artifact hints | | get_poc | GET /api/pocs/{id} | | get_success_criteria | GET /api/success-criteria (catalog) or joined with a POC's selections | | get_controlup_health | GET /api/controlup/device-overview?pocId=... (summarized) | | list_tracker_items | GET /api/tracker (filter mine/status/type) | | list_email_templates / get_email_template | GET /api/email-templates[/{id}] | | list_resources | GET /api/resources (search name/description/tags) |

Write tools (require a Read + write token from Settings):

| Tool | API | |------|-----| | update_poc_notes | PUT /api/pocs/{id} (appends a timestamped note) | | update_poc_status | PUT /api/pocs/{id} (manual_status) | | mark_report_sent | PUT /api/pocs/{id}/report-sent | | save_ai_report | POST /api/pocs/{id}/documents (+ /share for a SAS link) |

Also ships 3 prompts (post-call-update, draft-customer-email, qbr-prep) with POC-name auto-completion, report templates as MCP resources (poc-se-tools://templates/{id}), server instructions that teach Claude the link/scope rules, elicitation (confirm-before-write on status changes), and an experimental MCP Apps status card for get_poc_summary.

Self-update (v0.10.0+)

Users install the extension once. On each start, launcher.js checks <base_url>/downloads/server-version.json, downloads the newer single-file server bundle (poc-se-tools-server.mjs, built by esbuild in CI) with SHA-256 verification, caches it under ~/.poc-se-tools-mcp/, and runs it. Any failure falls back to the cached version, then to the server.js shipped in the package — updates can make the server stale, never broken. Opt out with POC_SE_TOOLS_NO_AUTO_UPDATE=1. A reinstall is only needed when manifest.json itself changes (new user-config fields, rename).

Releasing = push to main: CI rebuilds the bundle + version manifest and every client picks it up on its next Claude Desktop restart. Keep server.js VERSION in sync with package.json — the manifest build fails on skew.

Development

Server logic lives in server.js (createServer() with injectable fetch); index.js resolves the freshest server via launcher.js and connects stdio.

cd mcp-server
npm ci
npm test        # node:test suite — runs the server in-memory against a mocked API

CI runs the tests before every .mcpb build, so a failing suite blocks deploy.

Security

• Treat POC_SE_TOOLS_MCP_TOKEN like a password.
• Tokens are read-only by default; write tools need a token generated with "Read + write" scope. The API enforces scope server-side on every request.
• Tokens expire after 90 days; regenerate in Settings.
• Revoke in Settings if compromised.
• MCP runs as you — same POC visibility as the web app (SE: owned POCs; AE: assigned POCs, resolved live on each request).

Building the desktop extension (maintainers)

cd mcp-server
npm run build:mcpb    # → ../static/downloads/poc-se-tools.mcpb

The CI workflow runs this on every deploy, so the download in Settings always matches main. manifest.json version is synced from package.json by npm run sync:manifest (called by build:mcpb).

Publishing to npm (maintainers)

cd mcp-server
npm login          # personal npm account
npm publish        # unscoped: poc-se-tools-mcp

Bump version in package.json before each publish — it flows into manifest.json on the next build. Manual-config users pull poc-se-tools-mcp@latest.