--- name: connect-mcp description: Connect an AI agent or MCP client to Enping's OAuth-protected production MCP server. Use when the user asks to add Enping MCP, authorize project or environment access, verify the connection, or revoke it. Feedback implementation belongs to work-enping-feedback instead. --- # Connect to the Enping MCP server (production) ## What it is - **Endpoint:** `https://enping.app/mcp` (Streamable HTTP transport). - **Protocol:** dual-era MCP. `2026-07-28` clients use stateless per-request metadata, `server/discover`, routing headers, and cacheable tool lists; older clients can continue using the initialization-based protocol during migration. - **Auth:** OAuth 2.1 with dynamic client registration + PKCE — **no API key to paste**. On first connect the client opens a browser; the user signs in to Enping and picks exactly which projects/environments the connection may read. - **Access model:** never exceeds the signing-in user's own membership, and auto-narrows if their access is later revoked. Reads need a live read role; write and issue-linking tools need a live triage role (owner/admin/developer) on the item's project. - **Tools:** project/environment discovery; feedback list/detail, status, and assignment; GitHub repository/Issue links; plus one operation to open implementation work from feedback and one operation to finish its agent handoff. When a user provides a copied feedback prompt, use the focused `work-enping-feedback` skill after this connection is ready. Do not repeat the client setup flow during ordinary feedback work. ## Agent vs human steps An agent can run the `add` command and verify, but **the OAuth browser step (sign in + choose projects) must be done by the user** — the agent cannot click through it. Add the server, then hand off the one interactive step. ## Token-efficient usage - Start with `list_projects` / `list_environments` only when the user has not provided ids. - Call `list_feedback` with exactly one of `projectId` or `environmentId`, use the narrowest available `status` / `type` / `priority` filters, and set a small `limit` (5-25) unless the user asks for a broader page. - Follow `nextCursor` only when the user asks for more or the current task clearly needs another page. Do not crawl every granted project or environment by default. - Call `get_feedback` only for specific item ids that need comments, details, assignment, status changes, or GitHub issue creation. - For implementation, call `open_feedback_work` once with the supplied feedback item id and call `finish_feedback_work` once when stopping. Do not materialize local Enping context files or make the user maintain a separate work record. ## Codex Use the pinned `mcp-remote` stdio shim for Codex. It handles the remote OAuth flow and avoids native HTTP OAuth differences between Codex versions. Upgrade the pin deliberately after checking its OAuth storage migration notes: ```bash codex mcp add enping -- npx -y mcp-remote@0.8.1 https://enping.app/mcp ``` Verify: ```bash codex mcp get enping codex mcp list ``` If startup says the Enping server is not logged in or MCP startup is incomplete, remove it and use the `mcp-remote` command above: ```bash codex mcp remove enping codex mcp add enping -- npx -y mcp-remote@0.8.1 https://enping.app/mcp ``` ## Claude Code 1. Add the server (pick a scope): ```bash # user scope: available in all your projects on this machine (recommended) claude mcp add --transport http enping https://enping.app/mcp --scope user # project scope: shared with the team via a committed .mcp.json claude mcp add --transport http enping https://enping.app/mcp --scope project ``` Scopes: `local` (this project, only you — default), `project` (writes `.mcp.json` at repo root, shared), `user` (all your projects). 2. Authenticate. In the Claude Code REPL run `/mcp`, select **enping**, and choose **Authenticate**. A browser opens: - Sign in to Enping (or you'll be bounced through sign-in first). - On the consent screen, tick the **projects/environments** this connection may read, then **Authorize**. - The browser returns and the connection shows **connected**. 3. Verify: ```bash claude mcp list # shows enping as connected claude mcp get enping # transport + URL + auth status ``` Then ask the agent: "list my Enping projects" → it should call `list_projects`. - Remove / re-auth: `claude mcp remove enping` (then re-add), or re-run `/mcp` → Authenticate to refresh. - The committed project-scope file (`.mcp.json` at repo root) looks like: ```json { "mcpServers": { "enping": { "type": "http", "url": "https://enping.app/mcp" } } } ``` OAuth tokens are stored per-user by the client, never in this file — safe to commit. ## OpenCode Add a remote MCP server to `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "mcp": { "enping": { "type": "remote", "url": "https://enping.app/mcp", "enabled": true } } } ``` OpenCode should prompt for OAuth on first use. To trigger or inspect auth manually: ```bash opencode mcp auth enping opencode mcp list ``` ## Other clients The same endpoint and OAuth flow apply; only the config location differs. Each triggers the browser consent on first use. - **Cursor** — `.cursor/mcp.json`: ```json { "mcpServers": { "enping": { "url": "https://enping.app/mcp" } } } ``` - **VS Code (Copilot MCP)** — `.vscode/mcp.json`: ```json { "servers": { "enping": { "type": "http", "url": "https://enping.app/mcp" } } } ``` - **Claude Desktop** — Settings → Connectors → **Add custom connector**, URL `https://enping.app/mcp`. Older builds without remote OAuth support need the `mcp-remote` shim in `claude_desktop_config.json`: ```json { "mcpServers": { "enping": { "command": "npx", "args": ["-y", "mcp-remote@0.8.1", "https://enping.app/mcp"] } } } ``` ## Typical agent prompts once connected - "List my Enping projects." → `list_projects` - "Show the 10 latest open bugs for project ``." → `list_feedback` (status `open`, type `bug`, limit `10`) - "What are the 5 newest issues in the staging environment ``?" → `list_feedback` by `environmentId` with limit `5` - "Open feedback item `` with its comments." → `get_feedback` - "Mark feedback item `` as resolved." → `update_feedback_status` (status `resolved`; needs a triage role) - "Assign feedback item `` to a teammate." → `list_assignable_members`, then `assign_feedback` - "Create a GitHub issue from feedback item ``." → `list_github_links`, then `create_github_issue` ## Manage / revoke - Review and revoke connections in the dashboard: **user menu → Connected apps** (`https://enping.app/connections`). Revoking stops access immediately on the next tool call. ## Troubleshooting - **New Enping tools are missing:** restart the agent session or reconnect the MCP server. Long-lived clients may retain the tool catalog they received when the session started even though a fresh connection sees the current tools. - **Browser never opens / stuck unauthenticated:** trigger auth explicitly with `/mcp` → enping → Authenticate. Confirm you can reach `https://enping.app` in a browser. - **"No active access grant" / 403 from a tool:** the connection was revoked or you granted no scopes. Re-authenticate and select at least one project/environment. - **Tools return nothing:** you only granted scopes you can't currently read, or the project/environment id is outside the grant. Re-auth and widen the selection, or pass an id from `list_projects` / `list_environments`. - **Discovery fails in a stricter client:** the server exposes OAuth metadata at both the Better Auth path and the origin root (`/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`); make sure the client is pointed at `https://enping.app/mcp` exactly (no trailing path). - **Self-hosted / non-prod instance:** replace `https://enping.app` with that deployment's origin. OAuth issuer + endpoint URLs derive from the backend `SITE_URL`, so a misconfigured `SITE_URL` breaks the flow (see the `mcp-oauth-server` notes).