> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/integrations/ai-agents-mcp.md).

# AI Agents & MCP

Connect any MCP-capable AI agent to Pharos with the @pharosai/mcp server and operate skills to troubleshoot issues, investigate logs, and act on findings.

Pharos can be operated by an AI agent. The **`@pharosai/mcp`** server exposes your Pharos org to any Model Context Protocol (MCP) client, and a set of agent-agnostic **operate skills** teaches that agent how to use it—turning a plain-language question like *"why is checkout failing?"* or *"is anything broken?"* into the right diagnostic or action workflow.

These skills are the **operate (read/act) side** of Pharos automation—the mirror of [Triton instrumentation](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/pharos-triton-instrumentation.md), which is the **write side** that produces the logs an agent then reads.

{% hint style="info" %}
**Requires the MCP server.** These capabilities depend on the [`@pharosai/mcp`](https://www.npmjs.com/package/@pharosai/mcp) server being connected in your agent, plus a Pharos permission set assigned to the connected user (see [Prerequisites](#prerequisites)). The operate skills are Markdown playbooks that ship as developer/operator tooling—they are not deployed into your Salesforce org.
{% endhint %}

***

## What You Can Do

With the MCP server connected and the operate skills loaded, an agent can work across the full debugging loop without you knowing Pharos internals:

| You ask                            | The agent does                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| "Is anything broken right now?"    | Sweeps the org, ranks issues by impact, segments by area and recency                   |
| "Checkout is throwing errors"      | Scopes a log query from the symptom, groups by Issue, routes to a diagnosis            |
| "Why did Issue #1234 start?"       | Pulls stats, correlated logs, and AI root-cause analysis, interpreted against the data |
| "This isn't showing up in Pharos"  | Sets up a go-forward trace, then harvests and cleans up what it captures               |
| "Open a Jira ticket for this"      | Updates status/priority and promotes the Issue to an external ticket—after you confirm |
| "Alert me when this happens again" | Authors a basic notification or threshold alert, or routes you to the admin UI         |

Answers come back in **plain language first**; forensic detail (transaction IDs, stack traces, fingerprints) is available on request rather than leading.

***

## Prerequisites

Two things must be in place before an agent can operate your org:

1. **The `@pharosai/mcp` server**, connected in your MCP-capable agent.
2. **A Pharos permission set** assigned to the connected Salesforce user, which sets the agent's capability tier:

| Permission set   | Tier             | Enables                                                                 |
| ---------------- | ---------------- | ----------------------------------------------------------------------- |
| `Log_Read`       | **Read**         | View-only investigation—query logs, inspect issues, read analysis       |
| `Log_Read_Write` | **Read + Write** | Everything above, plus triage, tracing, and promoting issues to tickets |
| `Log_Admin`      | **Admin**        | Everything above, plus basic alerting setup (`Rule__c` access)          |

The connected org's identity and the active permission tier are surfaced **before** any investigation begins, so nobody investigates the wrong org—or hits a permission wall—silently.

***

## Connecting Your Agent

The skills behave identically across agents; only the invocation differs. The reference skills load automatically when a workflow needs them, so you never invoke them directly.

| Agent              | How to run a skill                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| **Claude Code**    | Slash commands, e.g. `/pharos:investigate-issue <id>`—they forward to the canonical skill files |
| **Cursor**         | `@`-mention the skill file and give it your request; Cursor loads it as context                 |
| **GitHub Copilot** | Reference the skill file in your prompt, or add it to `.github/copilot-instructions.md`         |
| **Any MCP agent**  | Paste the skill's contents into the conversation along with your request                        |

***

## How the Server Connects

For network and security reviews, the `@pharosai/mcp` server works like this:

* **Runs locally, over stdio** — your agent (Claude Code, Cursor, and so on) starts the server as a local process on your machine and talks to it over the MCP stdio transport. It opens no network port and exposes no URL, so there is nothing to allowlist on localhost (no `127.0.0.1/mcp`).
* **Uses your Salesforce CLI login** — at runtime it reads the org's instance URL and access token from your Salesforce CLI session (`sf org display --json`).
* **Calls one endpoint, in your own org** — a single Apex REST endpoint in that same org, `/services/apexrest/pharos/mcp`, over HTTPS, as you. Nothing else.
* **No Pharos-hosted service** — Pharos hosts no MCP service and holds no tokens.
* **Installed from npm** — installing or running the server with `npx` downloads the package from the npm registry.

***

## How the Skills Behave

Every workflow skill follows the same six-step loop, so an agent's behavior is predictable regardless of which task you start with:

1. **Prerequisites** — confirm the MCP is reachable, surface the target org, and detect the permission tier.
2. **Orient** — build (or reuse) a map of the org and translate your request onto it.
3. **Gather (read)** — query and correlate with small limits, then summarize in your language.
4. **Propose (write)** — state the intended change and wait for your confirmation.
5. **Act** — execute the confirmed action and report the result in plain language.
6. **Hand off** — suggest the natural next skill in the flow.

### Guardrails

Six principles are enforced in every skill:

* **Discover, don't hardcode** — field names carry per-org namespaces and status picklists are customizable, so skills resolve the org's real schema at runtime rather than assuming it.
* **Meet your language, both directions** — business terms go in without requiring Pharos taxonomy; plain-language answers come out first.
* **Walk the empty-result ladder** — before concluding "nothing found," a skill widens the time window, drops filters, re-checks vocabulary, and confirms org/tier.
* **Human-gated writes** — every mutation is proposed for `yes` / `modify` / `skip`, and skills de-duplicate before any create action.
* **Org and tier, up front** — surfaced before investigation starts.
* **Summarize, then drill** — small queries first; full detail only for the one to three records that matter.

***

## The Skill Catalog

The catalog spans a front-door router, two reference skills, the read/write debugging workflows, and a basic alerting on-ramp.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>🗂️ Skill Catalog</strong></td><td>Every operate skill, what it does, and how they hand off to one another</td><td><a href="https://docs.pharos.ai/configuration-guide/integrations/ai-agents-mcp/skill-catalog.md">Skill Catalog</a></td></tr></tbody></table>

Start at **`operate-pharos`**, the front door—it turns a request at any level of specificity into the right workflow. See the [Skill Catalog](https://docs.pharos.ai/configuration-guide/integrations/ai-agents-mcp/skill-catalog.md) for the full list and the typical hand-off path.

***

## Relationship to Triton and Pharos Admin

These operate skills **read and act**; they don't instrument code or configure the platform. Two boundaries are worth knowing:

* **When an area is dark** (nothing is logging), a workflow recommends the matching [Triton instrumentation](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/pharos-triton-instrumentation.md) skill (`instrument-apex`, `instrument-lwc`, `instrument-flows`) as a bridge, rather than dead-ending.
* **When setup exceeds basic alerting**—retention, masking, digests, or limits—the `set-up-alerting` skill names the right rule type and routes you to the admin UI with a docs pointer, such as [Log Retention](https://docs.pharos.ai/configuration-guide/log-retention.md) or [Notifications](https://docs.pharos.ai/configuration-guide/notifications.md).

***

## Related

* 🗂️ [Skill Catalog](https://docs.pharos.ai/configuration-guide/integrations/ai-agents-mcp/skill-catalog.md) — the full list of operate skills
* 🛠️ [Pharos Triton Instrumentation](https://docs.pharos.ai/platform-overview/pharos-platform-architecture/logs/log-ingestion-methods/pharos-triton-instrumentation.md) — the write side that produces the logs
* ⚙️ [Configuration Guide: Integrations](https://docs.pharos.ai/configuration-guide/integrations.md) — connecting external tools in Pharos Admin
* 🔔 [Configuration Guide: Notifications](https://docs.pharos.ai/configuration-guide/notifications.md) — alert and digest setup in the admin UI
