> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Photon MCP server

> Connect Claude, ChatGPT, Cursor, and other AI agents to your Photon account with the Model Context Protocol.

The Photon MCP server lets AI agents work with your Photon account through the
[Model Context Protocol](https://modelcontextprotocol.io). Your agent can set up
projects, connect channels, send and read messages, and check billing, using the
same API as the [API reference](/docs/beta/api-reference).

Use the hosted server. It runs at `https://mcp.photon.codes/mcp`, signs you in with
OAuth, and needs nothing installed. You need a Photon account; sign up in the
[dashboard](https://app.beta.photon.codes).

## Connect your client

Add the server to your client, then sign in to Photon in the browser window that
opens.

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    claude mcp add --transport http photon https://mcp.photon.codes/mcp
    ```

    Run `/mcp` in a Claude Code session and select **photon** to sign in.
  </Tab>

  <Tab title="Cursor">
    [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=photon\&config=eyJ1cmwiOiJodHRwczovL21jcC5waG90b24uY29kZXMvbWNwIn0%3D),
    or add this to `~/.cursor/mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "photon": {
          "url": "https://mcp.photon.codes/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="VS Code">
    [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=photon\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.photon.codes%2Fmcp%22%7D),
    or add this to `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "photon": {
          "type": "http",
          "url": "https://mcp.photon.codes/mcp"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add photon --url https://mcp.photon.codes/mcp
    codex mcp login photon
    ```
  </Tab>

  <Tab title="Claude and ChatGPT">
    Add a custom connector and enter `https://mcp.photon.codes/mcp` as its URL.

    * **Claude**: **Settings** > **Connectors** > **Add custom connector**.
    * **ChatGPT**: **Settings** > **Apps & Connectors** > **Create**. Developer
      mode must be turned on.
  </Tab>

  <Tab title="Other clients">
    Use `https://mcp.photon.codes/mcp` as the server URL. The server uses the
    Streamable HTTP transport and OAuth. If your client runs only local stdio
    servers, use the [local server](#run-the-server-locally).
  </Tab>
</Tabs>

## What your agent can do

The server offers a tool for each Photon API operation available to OAuth
clients. Ask for what you want in plain language:

* "Create a project called Support."
* "Add +1 415 555 0100 to the Support project's shared iMessage line."
* "How many messages did the Support project send this week?"
* "List the messages the Support project received today."
* "Show my organization's current billing usage."

Every call runs with your live permissions in the organization you authorized.
If your role can't perform an action, the tool returns an error and nothing
changes.

A hosted connection works in one organization at a time: the one you choose
when you sign in. To switch, revoke the client under
[Connectors](https://app.beta.photon.codes/account/connectors), then sign in
again from your client and choose the other organization. To work across
several organizations without switching, use the
[local server](#run-the-server-locally).

Agents can't manage single sign-on, organization members, OAuth clients, or
service identities, and can't change payment methods or plans. Do those in the
[dashboard](https://app.beta.photon.codes).

## Run the server locally

Run the open-source [`@photon-ai/mcp`](https://www.npmjs.com/package/@photon-ai/mcp)
package when your client supports only stdio servers, or when you can't
complete an OAuth sign-in, such as in CI. It offers the Photon API tools and
requires Node.js 22 or later.

<Steps>
  <Step title="Create an account service key">
    In the dashboard, open
    [Service keys](https://app.beta.photon.codes/account/service-keys) and
    create a key. It starts with `pho_ask_`. See
    [Credentials](/docs/beta/api-client/credentials) for what it can do.
  </Step>

  <Step title="Add the server to your client">
    <CodeGroup>
      ```bash Claude Code theme={null}
      claude mcp add photon --env PHOTON_API_KEY=pho_ask_... -- npx -y @photon-ai/mcp
      ```

      ```json JSON configuration theme={null}
      {
        "mcpServers": {
          "photon": {
            "command": "npx",
            "args": ["-y", "@photon-ai/mcp"],
            "env": { "PHOTON_API_KEY": "pho_ask_..." }
          }
        }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

An account service key acts for your account, with your role in every
organization you belong to. Put the real key only in a local client
configuration, never in a shared file or source control. The source code is on
[GitHub](https://github.com/photon-hq/mcp-server).

## Security

An agent acts with your permissions and can change your projects, so treat its
tool calls like your own:

* **Review changes before they run.** Your client decides when to ask before
  calling a tool. Keep approval turned on for tools that send messages, buy
  numbers or lines, or change and delete resources.
* **Watch for prompt injection.** Message contents, contact names, and webhook
  payloads come from other people. An agent that reads them can be told to do
  something you didn't ask for. Review tool calls that follow from reading
  that data.
* **Use only the official address.** Connect to `https://mcp.photon.codes/mcp`
  or the `@photon-ai/mcp` package from npm.

## Manage access

To disconnect a client, open
[Connectors](https://app.beta.photon.codes/account/connectors) in the dashboard
and revoke it. To stop a local server, delete its key under
[Service keys](https://app.beta.photon.codes/account/service-keys). A hosted
connection also ends when you leave the organization it was authorized for.

Revoking a hosted client stops it from getting new tokens. A token it already
holds keeps working until it expires.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.