Skip to content
Back to search

mcp

The Plenera MCP server, CLI, and agent skill.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/plenera-io--mcp/badge.svg)](/listings/plenera-io--mcp)

HTML

<a href="/listings/plenera-io--mcp"><img src="/api/listings/plenera-io--mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Node.js 22 or later is required.

git clone https://github.com/Plenera-io/mcp.git
cd mcp
npm ci
npm run build

Use `node` with the absolute path to `dist/cli.js` in your MCP client. To check a release, run `npm run typecheck`, `npm test`, and `npm pack`. The tarball includes the CLI, bundled API client, and skill.

Run `npm run generate:api` to regenerate the API types from the [public Plenera OpenAPI contract](https://app.plenera.io/api/v1/openapi.json). When changing a tool contract shared with the hosted MCP service, coordinate the corresponding change in the Plenera app and run the transport tests.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 101 lines
  1. # Plenera MCP
  2. Tools for projects, statuses, issue search/query, assigned work, issue creation/updates, self-assignment, comments and relations. Uses the generated Plenera API client and your API permissions; actions retain your agent identity.
  3. For the managed OAuth connection, add `https://app.plenera.io/mcp` to your client. See the [Plenera agent setup guide](https://app.plenera.io/docs/agents).
  4. For the local CLI, create a key in **Settings → Agents** or use a personal API token. Store it in your client's secret store and set your installation's `/api/v1` URL and workspace slug.
  5. ```json
  6. {
  7. "mcpServers": {
  8. "plenera": {
  9. "command": "npx",
  10. "args": ["-y", "@plenera/mcp@1.0.0"],
  11. "env": {
  12. "PLENERA_URL": "https://app.plenera.io/api/v1",
  13. "PLENERA_WORKSPACE": "your-workspace",
  14. "PLENERA_TOKEN": "<agent-key-from-secret-store>"
  15. }
  16. }
  17. }
  18. }
  19. ```
  20. The snippet works with Claude Code, Cursor and clients accepting `mcpServers`. In Codex, use the equivalent `[mcp_servers.plenera]` entry in `~/.codex/config.toml` with `command = "npx"`, `args = ["-y", "@plenera/mcp@1.0.0"]`, and pass the same environment variables through your secret environment. Do not commit credentials.
  21. ## Next assigned task
  22. `next_task` returns the caller's highest-priority **unstarted** assignment, or
  23. `issue: null` when none is ready. It uses the same order as the agent queue:
  24. urgent, high, medium, low, then no priority; board rank; due date (undated last);
  25. and id. It respects guest project access and does not claim or change the issue.
  26. Use a named agent key or personal credential, rather than a legacy workspace key.
  27. The API equivalent is `GET /orgs/{org}/agents/next`. Agent queue cursors are opaque
  28. and bound to the agent/workspace; keep them unchanged when loading another page.
  29. ## Source installation and publishing
  30. Node.js 22 or later is required.
  31. ```sh
  32. git clone https://github.com/Plenera-io/mcp.git
  33. cd mcp
  34. npm ci
  35. npm run build
  36. ```
  37. Use `node` with the absolute path to `dist/cli.js` in your MCP client. To check a release, run `npm run typecheck`, `npm test`, and `npm pack`. The tarball includes the CLI, bundled API client, and skill.
  38. Run `npm run generate:api` to regenerate the API types from the [public Plenera OpenAPI contract](https://app.plenera.io/api/v1/openapi.json). When changing a tool contract shared with the hosted MCP service, coordinate the corresponding change in the Plenera app and run the transport tests.
  39. ## Releases
  40. Update the package version and lockfile with `npm version <version> --no-git-tag-version`, then merge the version change into `main`. Push the matching stable tag, such as `v1.0.1`, on that commit. The [Publish to npm workflow](.github/workflows/publish.yml) checks the tag, installs the locked dependencies, tests the build, and publishes its tarball using npm Trusted Publishing.
  41. Run the workflow manually from `main` to verify the build and npm's GitHub OIDC connection without publishing a package version.
  42. ## Streamable HTTP
  43. Set `PLENERA_URL` and `PLENERA_WORKSPACE`, then run `node dist/cli.js --http` from a source checkout or `plenera-mcp --http` from an installed package. It listens on `127.0.0.1:3100/mcp` (`PORT` overrides). Each HTTP caller supplies its own `Authorization: Bearer <Plenera-key>`; no shared process token is used. The server is stateless and accepts POST only. Expose through a TLS reverse proxy if needed, retaining a loopback Host header; browser Origin requests are refused. Do not expose an unencrypted public listener. Upstream URLs must use HTTPS except loopback development.
  44. ## Agent skill
  45. Copy `skills/plenera` to your client's skill directory (Codex: `~/.codex/skills/plenera`; Claude Code: `~/.claude/skills/plenera`; Cursor: `.cursor/skills/plenera`). Configure the MCP connection first. Read the included `SKILL.md` for pagination, idempotency and completion evidence.
  46. Errors retain the API status, request ID and retry guidance. No automatic retries are performed. Keep a stable idempotency key when retrying an identical POST; read state after an uncertain write. Never share a key across tenants or print it in task comments.
  47. Issue tools accept `descriptionMarkdown` for native Markdown authoring. Do not
  48. also send `description`; editor JSON and plain legacy strings remain supported.
  49. Read results include canonical `descriptionMarkdown`. The `comment` tool's body
  50. is Markdown, and comment results include both editor JSON and `bodyMarkdown`.
  51. Agents can receive work without polling: owners/admins configure a public HTTPS
  52. endpoint in Settings → Agents → Wake-ups (or POST `/orgs/{org}/agents/{id}/endpoint`).
  53. Save the returned signing secret once. Assignment and structured comment mentions
  54. produce `agent.assigned` / `agent.mentioned` events with bounded Markdown context,
  55. recent comments, linked PRs and stable delivery ids. Verify `Plenera-Signature`
  56. against the raw body and a recent timestamp, and deduplicate event ids before
  57. starting work. The existing webhook queue handles retry/backoff and public-address
  58. pinning; redirects are not followed. Read delivery status through the endpoint
  59. GET route as that agent or an owner/admin. Pausing an endpoint, disabling its agent
  60. or deleting/moving the source issue prevents queued delivery. Destinations for
  61. agents are included independently of ordinary webhook quotas.
  62. ## Sessions and human steering
  63. After assignment, call `start_session` with the issue and an idempotency key.
  64. Use `session_activity` for steps, messages, PR links and optional reported USD
  65. cost. Call `update_session` periodically as a heartbeat, with `needs_input` when
  66. blocked, and `done` or `failed` to finish. `get_session` reads activity and supports
  67. before/after activity cursors. Human replies arrive as signed `agent.session.reply`
  68. events carrying the same session id and reply text; acknowledge by heartbeating
  69. or updating that session rather than creating a second one. Polling is unnecessary
  70. when a wake-up endpoint is connected.
  71. Sessions appear live on the issue, including their activity, PR links and reported
  72. cost. Queued/working sessions without progress for five minutes show Stale.
  73. The issue must be assigned to the agent before starting, and every session read
  74. rechecks project visibility. Only the owning agent reports progress; humans can
  75. steer it with replies. A saved reply explicitly reports when no active destination
  76. was available, so it cannot silently pretend to have notified a disconnected runner.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.