Skip to main content
The Photon MCP server lets AI agents work with your Photon account through the Model Context Protocol. Your agent can set up projects, connect channels, send and read messages, and check billing, using the same API as the 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.

​
Connect your client

Add the server to your client, then sign in to Photon in the browser window that opens.
Run /mcp in a Claude Code session and select photon to sign in.

​
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, then sign in again from your client and choose the other organization. To work across several organizations without switching, use the local server. 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.

​
Run the server locally

Run the open-source @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.
1

Create an account service key

In the dashboard, open Service keys and create a key. It starts with pho_ask_. See Credentials for what it can do.
2

Add the server to your client

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.

​
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 in the dashboard and revoke it. To stop a local server, delete its key under 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.