@pharosai/mcp

MCP server exposing Pharos logs, issues, traces, rules, digests, and admin tools to AI agents (Claude Desktop, Cursor, Claude Code, and any other MCP client).

Published on npm as @pharosai/mcp — MCP clients launch it on demand via npx, nothing to install manually.

Prerequisites

• Node.js ≥ 18 — node -v (the server is an ESM Node app).
• Salesforce CLI (sf) installed and authenticated to your org: sf org login web --alias my-alias.
• The Pharos package with MCP support deployed to that org (and MCP enabled for the org).

Use with an MCP client

Add to your agent's MCP config:

{
  "mcpServers": {
    "pharos": { "command": "npx", "args": ["-y", "@pharosai/mcp", "--org", "my-alias"] }
  }
}

For a dev/scratch org with a non-default namespace, add --namespace:

{
  "mcpServers": {
    "pharos": {
      "command": "npx",
      "args": ["-y", "@pharosai/mcp", "--org", "my-alias", "--namespace", "mypkgns"]
    }
  }
}

Claude Code CLI:

claude mcp add pharos -- npx -y @pharosai/mcp --org my-alias

Node version gotcha (common on macOS). MCP clients are GUI apps that don't run your shell's nvm, so npx may resolve to an old Node that can't run this package. If the client logs Cannot find module 'node:path' or an npx usage dump, point command at an absolute Node ≥ 18 binary instead of bare npx: "command": "/path/to/node18+/bin/node", "args": ["/path/to/@pharosai/mcp/dist/index.js", "--org", "my-alias"].

Flags

| Flag | Purpose | Default | |---|---|---| | --org <alias> | Target org (else SF_TARGET_ORG, else CLI default) | CLI default | | --namespace <ns> | Package namespace for the REST path /services/apexrest/<ns>/mcp | pharos | | --read-only | Advertise only non-mutating tools | off | | --tools <glob,...> | Client-side allowlist (comma-separated * globs) | all | | --deny <glob,...> | Client-side denylist | none |

How it works

On startup the server runs sf org display to get an access token + instance URL, then calls the pharos_describe Apex tool, which returns the catalog of tools the authenticated user is entitled to call. The server advertises exactly those, and forwards each call to the org as that user — so native object/field/sharing security applies. Auth and token refresh are delegated entirely to the sf CLI; no secrets are stored by this server.

Tools

The exact set advertised depends on your permissions and tier: read (object access), write (Pharos_MCP_Write permission set), admin (Pharos_MCP_Admin). Tier is shown in parentheses below (unmarked = read). ⚠️ = live but partial (some sub-features deferred).

Logs

• pharos_query_logs — query logs by date / hash / category / level
• pharos_get_log — full log record by Id

Issues

• pharos_query_issues — query issues by status / category / priority / date
• pharos_get_issue — full issue by Id (incl. analysis fields)
• pharos_update_issue — update status / assignee / priority (write)
• pharos_add_issue_comment ⚠️ — comment on the issue's linked Jira/Azure DevOps ticket; GitHub not supported (write)

AI analysis

• pharos_analyze_issue — run AI analysis and block until it finishes (~2.5 min max), returning the result in one call (write)
• pharos_get_analysis — fetch stored AI analysis: status, details, and results (parsed body per analysis type)

Change tracking

• pharos_query_changes — query Setup Audit Trail changes

Traces

• pharos_list_traces — list trace schedules
• pharos_get_trace_results — trace results + attached-log metadata (titles/sizes, not bodies)
• pharos_create_trace — create a trace schedule with windows (write)
• pharos_stop_trace — deactivate a trace schedule (and cascade) (write)

Rules

• pharos_list_rules — list rules (alerting / monitoring / ticketing)
• pharos_get_rule — rule with its filters + actions
• pharos_toggle_rule — activate / deactivate a rule (write)
• pharos_create_rule ⚠️ — create a rule (criteria wired; limited action types) (write)
• pharos_update_rule ⚠️ — update a rule (same caveat) (write)

Tickets

• pharos_list_ticket_options — list projects, issue/work-item types, and (Jira) priorities to use with create_ticket (write)
• pharos_create_ticket ⚠️ — create a Jira/Azure DevOps ticket from an issue; GitHub not supported. title/description resolve Issue merge fields; project/issueType accept id or key/name (write)

Digests

• pharos_list_digests — list digest rules
• pharos_get_digest — full digest rule by Id
• pharos_create_digest ⚠️ — create a digest (scalar fields; schedule shorthand hourly/daily/weekly/monthly only) (admin)
• pharos_update_digest ⚠️ — update a digest (same caveats) (admin)
• pharos_run_digest — trigger digest generation (write)

Org & settings

• pharos_get_org_info ⚠️ — org/user info + connected orgs (no pharosVersion)
• pharos_get_settings — Logger/Pharos settings grouped by section (admin)
• pharos_update_settings — update core settings; metadata/callout/scheduler fields are read-only (admin)

Meta

• pharos_describe — list the tools the current user is entitled to call

Develop / publish

nvm use            # Node 20 (see .nvmrc)
npm install
npm test           # vitest
npm run build      # tsc -> dist/
npm publish        # public access preconfigured via package.json publishConfig

Publishing requires membership in the pharosai npm org and 2FA — pass --otp <code>, or use an automation / granular access token with 2FA bypass in ~/.npmrc.