@phenomenalorg/mcp

Connect an MCP client to Phenomenal — your school community's site, events, volunteers, store, donations and communications — over stdio.

Phenomenal's MCP server is a normal remote MCP server at https://api.phenomenal.org/mcp, and most clients no longer need this package: they can speak Streamable HTTP directly and handle the browser sign-in themselves. Reach for this bridge when your MCP client only speaks stdio.

Connect without the bridge (preferred)

Claude Code

claude mcp add --transport http phenomenal https://api.phenomenal.org/mcp

Then run /mcp in Claude Code and pick phenomenal to sign in.

Codex CLI

codex mcp add phenomenal --url https://api.phenomenal.org/mcp
codex mcp login phenomenal

Claude Desktop

Settings → Connectors → Add custom connector → paste https://api.phenomenal.org/mcp → Connect, and approve the browser consent screen.

Connect with the bridge (stdio-only clients)

Add this to your client's MCP server config:

{
  "mcpServers": {
    "phenomenal": {
      "command": "npx",
      "args": ["-y", "@phenomenalorg/mcp"]
    }
  }
}

The first launch opens your browser, you approve access to your school's Phenomenal organization, and the bridge remembers the grant. There is no API key to create, paste or rotate.

Point it somewhere else with a URL:

{
  "mcpServers": {
    "phenomenal": {
      "command": "npx",
      "args": ["-y", "@phenomenalorg/mcp", "--url", "https://api.ph-dev.org/mcp"]
    }
  }
}

Command line

npx @phenomenalorg/mcp [<url>] [--url <url>] [--skill [dir]] [--logout] [--version] [--help]

| Flag | What it does | | --------------- | --------------------------------------------------------------------- | | --url | The Phenomenal MCP endpoint. Default https://api.phenomenal.org/mcp | | --skill [dir] | Install the Phenomenal agent skill (see below) | | --logout | Forget the saved sign-in for that server and exit | | --version | Print the version and exit | | --help | Print usage and exit |

Sign out of one server:

npx @phenomenalorg/mcp --logout
npx @phenomenalorg/mcp --logout --url https://api.ph-dev.org/mcp

The agent skill

Connecting gives your assistant the tools. The skill gives it the working habits that go with them: call list_my_orgs before anything else, draft → preview → publish, never confirm a send on its own initiative, keep member details out of anything public.

For page authoring, read phenomenal://instructions and call get_page_authoring_state first: canonical content and revisions define the edit. Use preview_page_changes with DRAFT, then save_page_changes to save content and its document Look together privately. Read the canonical state back after saving. Page-wide CSS belongs to Looks; preserve enabled-language HTML and unrelated blocks when changing appearance or making a targeted edit.

Publication is separate: review a fresh PUBLISH preview, then call publish_page with its exact required review receipt only after explicit human confirmation. Saving a draft does not publish it. The generated skill and tool references describe the current inputs and review requirements.

npx @phenomenalorg/mcp --skill .claude/skills   # install it into a project
npx @phenomenalorg/mcp --skill                  # install into ./.claude/skills if it
                                                # exists, else print SKILL.md

--skill <dir> writes a phenomenal/ folder into the directory you name: SKILL.md plus references/ — the full tool catalog, the run_mutation long tail, and how to read the GraphQL schema. An existing install is replaced; the skill is generated from the server's own tool registry, so there is nothing in it worth keeping across an update.

For a client with no skills feature, point it at https://phenomenal.org/agents instead — the same briefing, plus the install recipes, as one plain-text page it can fetch.

Where your sign-in is kept

~/.phenomenal/mcp/<server>.json, one file per server, written 0600 inside a 0700 directory. It holds the bridge's OAuth client registration and the access/refresh tokens issued to it — treat it exactly like an SSH private key. --logout deletes it; revoking the connection inside Phenomenal invalidates it from the other end.

How it works

• Sign-in is OAuth 2.1 with PKCE and dynamic client registration. The bridge registers itself as the public client Phenomenal MCP, opens your browser, and catches the redirect on a loopback listener bound to 127.0.0.1 — never a routable interface.
• Once you have a token the bridge is a message pump: everything your client writes on stdin goes to Phenomenal over Streamable HTTP and everything Phenomenal sends back goes to stdout, notifications included.
• stdout is the protocol stream. Every diagnostic the bridge prints goes to stderr, so if something looks wrong, that is where to look.

Requires Node 20 or newer.

Support

Issues and questions: https://github.com/PTO-pro/ptopro/issues.