# Photon MCP

```json
{
  "name": "Photon MCP",
  "slug": "photon_mcp",
  "url": "https://composio.dev/toolkits/photon_mcp",
  "markdown_url": "https://composio.dev/toolkits/photon_mcp.md",
  "logo_url": "https://logos.composio.dev/api/photon_mcp",
  "categories": [
    "collaboration & communication"
  ],
  "is_composio_managed": false,
  "updated_at": "2026-10-28T05:35:19.949Z"
}
```

![Photon MCP logo](https://logos.composio.dev/api/photon_mcp)

## Description

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with Photon MCP or direct API to manage messaging projects, search conversations, configure voice profiles, and handle webhooks through natural language.

## Summary

Photon MCP is a hosted messaging service for managing projects, conversations, resources, voice profiles, and webhooks.
It gives teams a simple way to organize messaging data and automate communication workflows.

## Categories

- collaboration & communication

## Toolkit Details

- Tools: 126

## Images

- Logo: https://logos.composio.dev/api/photon_mcp

## Authentication

- **Dcr Oauth**
  - Type: `custom`
  - Description: Dcr Oauth authentication for Photon MCP.
  - Setup:
    - Configure Dcr Oauth credentials for Photon MCP.
    - Use the credentials when creating an auth config in Composio.

## Suggested Prompts

- List recent conversations in my Photon project
- Create a webhook for new Photon conversations
- Update the voice profile for customer support

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `PHOTON_MCP_ASSIGN_SMS_LINE_CAMPAIGN` | Assignsmslinecampaign | Assign or replace SMS line campaign Attach a ready campaign from this project’s organization to its line. Requires platforms:write for the project; human and machine actors retain their authenticated identity. Requires a permanent Idempotency-Key and the current assignment version. Provider provisioning runs asynchronously. |
| `PHOTON_MCP_ASSIGN_VOICE_LINE_PROFILE` | Assignvoicelineprofile | Assign Voice line profile Assigns or replaces a line's explicit additional-profile override when the resource version matches. The current default cannot be assigned explicitly. The pstn_voice ability remains the admission source of truth. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_BATCH_UPDATE_VOICE_LINE_PROFILE_ASSIGNMENTS` | Batchupdatevoicelineprofileassignments | Batch update Voice line assignments Atomically sets additional-profile overrides or switches lines back to the project default for up to 100 Voice-capable lines. A null profileId means use the default. Every expected resource version must match or no line changes. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_BEGIN_TOTP_ENROLLMENT` | Begintotpenrollment | Begin TOTP enrollment Requires a first-party interactive Account credential authenticated no more than 300 seconds ago. Returns one-time secret material. |
| `PHOTON_MCP_CANCEL_OPERATION` | Canceloperation | Cancel operation Withdraws a provision that has not been fulfilled yet. This is an operations action rather than a DELETE, because there is nothing to delete: no resource exists until the work commits. Whether it is accepted depends on the resource type — a dedicated iMessage line may sit waiting on inventory for hours and withdrawing costs nothing, while an SMS number is cancellable during inventory waiting and answers 409 once the workflow commits to its first provider order. Campaign assignment and detachment operations cannot be cancelled in any state. Wait for completion before requesting another change; that new change is not a guaranteed rollback. The output-only `cancellable` field is a snapshot; the cancellation transaction always checks the current phase under a row lock. A cancel that loses the race against the work finishing also answers 409: the resource exists and is billed for, so what you want then is to release it. Nothing is charged for a cancelled provision — billing runs after the work, so there is never anything to refund. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_CHECK_PROJECT_SLUG_AVAILABILITY` | Checkprojectslugavailability | Check project slug availability Reports whether createProject would accept `slug` right now. Advisory: only the create itself allocates, so a caller must still handle SLUG_TAKEN. A malformed slug is rejected on shape; a reserved slug, a slug held by an active project, and a slug retired with a deleted project each answer `available: false` with a reason. |
| `PHOTON_MCP_COMMIT_ACCOUNT_PROFILE_PICTURE` | Commitaccountprofilepicture | Commit profile picture Commits a profile picture previously uploaded through createAccountProfilePictureUpload. Call this only after the direct multipart upload succeeds, using the uploadId from the same upload session and a stable Idempotency-Key. The service validates the temporary object's ownership, size, content type, image bytes, dimensions, encryption, and age before changing the Account. |
| `PHOTON_MCP_COMMIT_AGENT_PROFILE_AVATAR` | Commitagentprofileavatar | Commit agent avatar Commits an agent avatar previously uploaded through createAgentProfileAvatarUpload. Call this only after the direct multipart upload succeeds, using the uploadId from the same upload session and a stable Idempotency-Key. The service validates the temporary object's Project ownership, size, content type, image bytes, dimensions, encryption, and age before changing the agent profile. |
| `PHOTON_MCP_CONNECT_EMAIL_DOMAIN` | Connectemaildomain | Connect email domain Reserves a normalized DNS domain and starts its durable email-provider setup. The accepted provision consumes one email-domain entitlement slot until it fails, is cancelled, or becomes a live resource; the plan's email.max_email_domains value sets the project limit. The customer resource does not exist until provider identity and DNS setup reach READY; poll the returned operation for progress. A domain may have only one unfinished provision or live resource globally. Email domains have no additional per-domain charge. The Idempotency-Key is required and permanent: replaying the same key and canonical domain returns the original operation forever. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_CONNECT_TELEGRAM_BOT` | Connecttelegrambot | Connect Telegram bot Starts a free managed Telegram bot connection. Each project may have one unfinished Telegram provision, including user interaction and failure cleanup. A different Idempotency-Key while one is active returns 409 TELEGRAM_PROVISION_IN_PROGRESS with its operationId and operationUrl; resume it, cancel it while cancellation is available, or wait for it to finish. Rejected keys remain reusable. Open detail.setupUrl to create a new bot, whose name and username are chosen in Telegram, or to connect an existing managed bot, then poll Location. The link remains usable while the operation is active and never expires. Replaying the same Idempotency-Key returns the original operation, even after completion or while a newer setup is active. POST, GET and list share the same operation details. The API includes detail.setupUrl only for callers with platforms:write for the project; read-only callers receive the other details unchanged. |
| `PHOTON_MCP_COUNT_FILTERED_VERIFICATION_CODES` | Countfilteredverificationcodes | Count filtered verification codes Counts the verification codes Photon kept from this project's dedicated lines and numbers, optionally for one `platform`. Without `receivedAfter` and `receivedBefore` the window is the 30 days before the request; a window longer than 366 days is rejected. The response echoes the window it resolved, so the number always says which period it covers. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_COUNT_MESSAGES` | Countmessages | Count Messages Counts matching Messages before pagination. Delivery updates do not add Messages; results are eventually consistent. |
| `PHOTON_MCP_COUNT_PROJECTS` | Countprojects | Count projects Counts the projects the same filter would list. The count is read from the primary, so it is authoritative rather than replica-lagged. |
| `PHOTON_MCP_COUNT_RESOURCE_FILTERED_VERIFICATION_CODES` | Countresourcefilteredverificationcodes | Count a line's filtered verification codes Counts the verification codes Photon kept from one dedicated line or number. Without `receivedAfter` and `receivedBefore` the window is the 30 days before the request; a window longer than 366 days is rejected. The response echoes the window it resolved, so the number always says which period it covers. Answers 404 unless the project holds the resource now. Codes from an earlier tenure stay in the project-wide list. Filter by `platform` — a number receives both SMS and WhatsApp. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_COUNT_SPACES` | Countspaces | Count Spaces Counts distinct Spaces matching the list filters; multiple matching Messages count once. Results are eventually consistent. |
| `PHOTON_MCP_COUNT_USERS` | Countusers | Count Users Counts distinct Users matching the list filters, including incoming senders or outgoing recipients selected by Message filters. Results are eventually consistent. |
| `PHOTON_MCP_CREATE_ACCOUNT_PROFILE_PICTURE_UPLOAD` | Createaccountprofilepictureupload | Create profile picture upload Creates a ten-minute, Account-bound presigned S3 POST for a JPEG, PNG, or WebP profile picture up to 5 MiB. Copy every returned formFields entry into a multipart/form-data request to uploadUrl, append the local file as the final form part, and upload it directly without sending Photon credentials. After the upload succeeds, call commitAccountProfilePicture with the returned uploadId. Do not cache or log the upload URL or form fields. |
| `PHOTON_MCP_CREATE_AGENT_PROFILE_AVATAR_UPLOAD` | Createagentprofileavatarupload | Create agent avatar upload Creates a ten-minute, Project-bound presigned S3 POST for a JPEG, PNG, or WebP agent avatar up to 5 MiB. Copy every returned formFields entry into a multipart/form-data request to uploadUrl, append the local file as the final form part, and upload it directly without sending Photon credentials. After the upload succeeds, call commitAgentProfileAvatar with the returned uploadId. Do not cache or log the upload URL or form fields. |
| `PHOTON_MCP_CREATE_DEFAULT_VOICE_PROFILE` | Createdefaultvoiceprofile | Create default Voice profile Creates the project default Voice profile when absent. An identical replay returns the existing default without changing its version; a different existing default conflicts. Direction configuration is managed separately. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_CREATE_OR_GET_SPACE` | Createorgetspace | Create or get a Space Creates or returns a project Space. Idempotency-Key is required for every platform and binds the project, platform and initial User IDs (unordered except the iMessage creator in first position) for 24 hours after workflow completion. Concurrent matching requests join the same operation; conflicting reuse returns 422 once its outcome is available. A new email key creates a new thread; direct Spaces and SMS groups converge by participants. Every creation and successful replay requires at least one currently project-owned Agent, or for iMessage a shared-line Agent in a direct Space whose peer has an active Assignment of this project on that line. For iMessage, an existing exact match is reused; otherwise the first participant must be a project-owned dedicated phone Agent and creates the native direct chat or group. Multiple matching native groups return SPACE_AMBIGUOUS; incomplete group membership cannot establish an exact match. Replays return 200 and the current stored Space, with Idempotent-Replayed: true. A timeout does not cancel accepted work: retry the same key and input. |
| `PHOTON_MCP_CREATE_OR_GET_USER` | Createorgetuser | Create or get a User Creates or reconciles a User by normalized handle. WhatsApp and iMessage phone classification uses line allocation and project ownership; New iMessage email handles start as Human without lookup; existing email identities retain their producer-observed classification and ownership. WhatsApp Business uses project ownership. These three platforms perform no provider profile or enrichment fetch. Shared Agents expose type=shared without ownership IDs; dedicated Agents expose resourceId for this project or pairwise managedBy for another project. Dedicated lines without an active owner are unavailable. SMS retains its existing ownership and phone number enrichment behavior. Email retains domain ownership resolution, lowercase ASCII domains and case-preserved local parts. Dependency failures fail before classification writes. The natural identity is the project path ID, platform, and handle. Retrying after a committed creation whose response was lost returns the same User with 200 rather than replaying 201. |
| `PHOTON_MCP_CREATE_PROJECT` | Createproject | Create project Creates in the authorized organization. In addition to account credentials, explicitly granted Service Identity API keys and M2M tokens may create projects. Project API keys cannot create projects. Creator and private credential evidence come only from the trusted authorization context. The caller-selected slug is immutable, must be 3 to 63 lowercase ASCII alphanumerics separated by single hyphens, and cannot be reserved or held by any active or deleted project. |
| `PHOTON_MCP_CREATE_SHARED_LINE_ASSIGNMENT` | Createsharedlineassignment | Create shared line assignment Maps an end user's iMessage handle — an E.164 phone number or an email address — onto one of the project's pooled shared iMessage lines, consuming a seat from the project's entitlement. The assigned number is allocated by the server. When an email address is supplied in `email` the user is sent an invite asynchronously to that address; it is never inferred from the handle, and the response never reports whether the send succeeded. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_CREATE_VOICE_PROFILE` | Createvoiceprofile | Create Voice profile Creates a direction-neutral additional Voice profile. The project default must already exist. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_CREATE_WHATSAPP_SHARED_LINE_ASSIGNMENT` | Createwhatsappsharedlineassignment | Create WhatsApp shared line assignment Maps an end user's phone number onto one of the project's pooled shared WhatsApp lines, consuming a seat from the project's WhatsApp entitlement. The assigned number is allocated by the server. When an email address is supplied the user is sent an invite asynchronously; the response never reports whether that succeeded. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_CREATE_WHATSAPP_VOIP_SENDER` | Createwhatsappvoipsender | Create WhatsApp VoIP sender Registers an active, SMS-capable Photon VoIP line on this project's connected WhatsApp Business Account. The account is resolved server-side; callers never select a WABA. The platform creates or reuses the Meta number, requests and consumes the SMS ownership code internally, verifies it, and registers the sender. displayName is optional; when omitted the project agent profile name is snapshotted before acceptance. The VoIP line remains a separate resource and never receives the whatsapp_business ability. |
| `PHOTON_MCP_DELETE_ACCOUNT` | Deleteaccount | Delete account Deletes the authenticated account and returns its account tombstone. The operation is rejected while the account still owns organizations; transfer or close those organizations before retrying. This endpoint acts on the caller's account and does not accept another account's identifier. |
| `PHOTON_MCP_DELETE_PROJECT` | Deleteproject | Delete project Starts deletion of the identified project using a credential authorized for project management. Inspect the documented response and use getProjectClosureStatus with the organization and project identifiers to read closure progress. A project API key is not an accepted credential for this operation. |
| `PHOTON_MCP_DELETE_TOTP_FACTOR` | Deletetotpfactor | Delete a TOTP factor Requires a first-party interactive Account credential authenticated no more than 300 seconds ago. Ownership is verified before deletion. |
| `PHOTON_MCP_DELETE_VOICE_PROFILE` | Deletevoiceprofile | Delete Voice profile Deletes an additional profile when expectedVersion matches. Assigned profiles require force=true, which atomically removes every stored override so affected lines follow the default. The default can never be deleted. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_DELETE_VOICE_PROFILE_INBOUND` | Deletevoiceprofileinbound | Delete Voice inbound configuration Removes a profile's inbound destination when the shared profile version matches. The profileId may identify the default or an additional profile. The profile and its line assignments remain. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_DELETE_VOICE_PROFILE_OUTBOUND` | Deletevoiceprofileoutbound | Revoke Voice outbound credential Revokes outbound calling for a profile when the shared profile version matches. The profileId may identify the default or an additional profile. The profile, inbound destination, and line assignments remain. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_DELETE_WEBHOOK_DESTINATION` | Deletewebhookdestination | Delete webhook destination Deletes the selected project's destination and returns its stable tombstone. Repeated deletion returns the deletion representation. This operation removes the destination configuration; it is separate from disabling a destination through an update. |
| `PHOTON_MCP_DISCONNECT_WHATSAPP_BUSINESS_ACCOUNT` | Disconnectwhatsappbusinessaccount | Disconnect WhatsApp Business account Disconnects every attached WhatsApp sender, then unsubscribes our app and removes the project's business account connection. Photon VoIP lines and the numbers in Meta remain. Requires Idempotency-Key. Poll the returned operation; provider refusals appear as operation failures and retain the account for retry with a new key. New signups are blocked while disconnecting, and existing provisions must finish before this request can be accepted. |
| `PHOTON_MCP_GET_ACCOUNT` | Getaccount | Get account Returns the profile of the authenticated account. The account is selected from the credential rather than a request parameter. A missing or deleted account is reported as an error instead of an empty profile. |
| `PHOTON_MCP_GET_AGENT_PROFILE` | Getagentprofile | Get agent profile Returns the agent profile belonging to the identified project. The profile is project-scoped and is distinct from the authenticated account's personal profile. Use the dedicated avatar operations when uploading or removing an agent avatar. |
| `PHOTON_MCP_GET_ATTACHMENT` | Getattachment | Get attachment Returns an Attachment's metadata. Use the content endpoint to download its bytes. |
| `PHOTON_MCP_GET_BILLING_OPERATION` | Getbillingoperation | Get billing operation Returns the authoritative state of a billing operation belonging to the selected project. Use it to recover or poll a plan-change request until the operation reaches success or failure. An accepted request is not evidence that the plan change has completed. |
| `PHOTON_MCP_GET_BILLING_OVERVIEW` | Getbillingoverview | Get project billing overview Returns the selected project's plan information, entitlements and current billing-period usage. This operation reads project billing state; it does not change plans or the payer's payment method. Organization-level plans are available through the organization billing overview. |
| `PHOTON_MCP_GET_CURRENT_ORGANIZATION` | Getcurrentorganization | Read the credential's organization Reads the organization the credential is bound to: the organization an OAuth grant was consented for, or a Service Identity's own organization. Use it to discover which organization an integration acts for, and pass its organizationId to organization-scoped operations. |
| `PHOTON_MCP_GET_DEFAULT_VOICE_PROFILE` | Getdefaultvoiceprofile | Get default Voice profile Gets the profile currently selected as the project default, including its optional inbound delivery state. Requires platforms:read bound to the path project. |
| `PHOTON_MCP_GET_EFFECTIVE_TERMS` | Geteffectiveterms | Get the project's effective billing terms Returns what the selected project is billed on now, per category it holds: the plan as its subscription has it, with any override applied, each fixed charge at the subscription's price and quantity, and resolved entitlements; where the plan comes from; how invoices are paid; the current period and next billing date; and any downgrade or cancellation waiting for the period end. Supply both organizationId and projectId; the organization must pay for the project. This operation does not change billing. |
| `PHOTON_MCP_GET_EMAIL_DELIVERY_METRICS` | Getemaildeliverymetrics | Get email delivery metrics Reads cached supplementary email series for the exact Project and rolling day or week. Coverage is eligible single-recipient messages; multi-recipient and simulator traffic is excluded. Observed complaints include reported feedback only. Missing data is distinct from zero. Original timestamps and availability are preserved; freshness describes retrieval, not complete event coverage. These series are not complete recipient totals, billing totals or Photon reputation rates. This read never queries the delivery provider or authorizes sending. Requires platforms:read for the path Project. |
| `PHOTON_MCP_GET_EMAIL_SENDING_POLICIES` | Getemailsendingpolicies | Get email sending policies Reads Organization email recipient allowances shared across all its Projects, with rolling 60-second and 24-hour windows. Also returns Project and Organization review status and Photon policy pauses. Projects have no separate recipient quota. These limits are independent of subscription allowances. A policy pause blocks sending; an unpaused policy does not guarantee that every domain, suppression or account check permits a send. Requires platforms:read for the path Project. |
| `PHOTON_MCP_GET_MESSAGE` | Getmessage | Get a Message Returns one stored Message by canonical Photon Message ID on any supported contract platform. The globally unique Message ID is resolved within the authorized Project. Unsupported platform Messages are outside this collection and return MESSAGE_NOT_FOUND. |
| `PHOTON_MCP_GET_MESSAGE_METRICS_BACKFILL` | Getmessagemetricsbackfill | Get metrics backfill status Returns historical metrics update progress. Completion reflects lastVerifiedAt; queries remain available during updates. |
| `PHOTON_MCP_GET_MESSAGE_METRICS_SQL_SCHEMA` | Getmessagemetricssqlschema | Get metrics SQL schema Returns the message_events and call_events SQL schema, supported queries, and limits for the selected API version. |
| `PHOTON_MCP_GET_MFA_STATUS` | Getmfastatus | Get MFA status Requires a first-party interactive Account credential. Account Service Keys and third-party OAuth grants are not accepted. |
| `PHOTON_MCP_GET_OPERATION` | Getoperation | Get operation Reads one operation using the same operation representation as creation and list. The API includes detail.setupUrl only with platforms:write for this project. This is the polling endpoint every asynchronous request here points its Location at, and it resolves from the moment that request is accepted — an operation is committed before its work is dispatched, so there is no window in which the URL 404s. Poll until `state` is one of `succeeded`, `failed` or `cancelled`, pacing from the Retry-After the accepting response returned. While an email domain waits for DNS, `detail` always contains the manual records and may additionally contain `automaticSetup` with a signed provider URL to open separately. Once the operation has produced a resource, the response carries that resource too, so the poll that finishes is also the one that tells you what you got. `succeeded` means the work is done; billing runs behind it and is not something the caller waits on. Operations are never purged, so a 404 means the id was never this project's. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_GET_ORGANIZATION_BILLING_OVERVIEW` | Getorganizationbillingoverview | Get organization billing overview Returns the selected organization’s billing subscription and entitlementsVersion. The subscription can be null. Read the returned plan, charges and entitlements to inspect organization billing; this operation does not purchase or change a plan. |
| `PHOTON_MCP_GET_ORGANIZATION_CREDIT` | Getorganizationcredit | Get organization credit Returns the credit the selected organization holds: on credit notes, such as the unused time of a plan an upgrade replaced or the unused days of a prorated fixed charge it released, and in its wallet: the credit Photon granted it, such as a new account's first organization's welcome credit, and any prepaid credit it bought. It offsets that organization's invoices of any kind except one-off invoices, credit notes first. Reading it does not apply or change credit. |
| `PHOTON_MCP_GET_ORGANIZATION_PAYMENT_METHOD` | Getorganizationpaymentmethod | Get organization payment method Reports whether the selected organization has a card on file and returns its documented payment-method metadata. Reading this endpoint does not collect a new card or create a checkout session. |
| `PHOTON_MCP_GET_ORGANIZATION_TERMS` | Getorganizationterms | Get the organization's effective billing terms Returns what the selected organization is billed on now on its own subscription, such as SSO and 10DLC campaigns: the plan as the subscription has it, with any override applied, each fixed charge at the subscription's price and the quantity the organization holds, and resolved entitlements; where the plan comes from; how invoices are paid; the current period and next billing date; and any downgrade or cancellation waiting for the period end. subscription has a project subscription's terms without its category, and is null when the organization holds none. Project subscriptions are read per project. This operation does not change billing. |
| `PHOTON_MCP_GET_PROJECT` | Getproject | Get project Returns the identified project's settings for an authorized caller. The credential must be allowed to access that project; possession of an unrelated project's key does not provide access. Missing and deleted projects are reported through the documented error responses. |
| `PHOTON_MCP_GET_PROJECT_CLOSURE_STATUS` | Getprojectclosurestatus | Get project closure status Returns closure progress for projectId within organizationId, including deletionOperationId, domain progress and ready. This read operation does not initiate deletion. |
| `PHOTON_MCP_GET_PROJECT_IMESSAGE_PLATFORM` | Getprojectimessageplatform | Get project iMessage platform Reports whether the project is on shared or dedicated iMessage lines, derived from its billing entitlements. Shared mode carries the seat cap. Both say whether a dedicated line requested now would be assigned without waiting. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_GET_PROJECT_WHATSAPP_PLATFORM` | Getprojectwhatsappplatform | Get project WhatsApp platform Reports whether the project is on shared or dedicated WhatsApp lines, derived from its billing entitlements. Shared mode carries the seat cap. Both say whether a dedicated line requested now would be assigned without waiting. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_GET_RESOURCE` | Getresource | Get resource Reads one resource the project holds. A released number stays readable and reads `retired`, because it remains part of this project's history. A dedicated line given back does NOT: returning it to inventory is what makes it claimable by someone else, so it answers 404 and the operation that returned it is the record that this project once held it. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_GET_SHARED_LINE_ASSIGNMENT` | Getsharedlineassignment | Get shared line assignment Reads one shared line assignment. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_GET_SMS_LINE_CAMPAIGN_ASSIGNMENT` | Getsmslinecampaignassignment | Get SMS line campaign assignment Read the last confirmed campaign and current eligibility. Follow changes through their operations. Eligibility is a control-plane assessment, not a delivery or recipient-consent guarantee. |
| `PHOTON_MCP_GET_SPACE` | Getspace | Get a Space Returns one stored Space by canonical Photon Space ID. A Space of a kind its platform does not support returns OPERATION_UNAVAILABLE. |
| `PHOTON_MCP_GET_USER` | Getuser | Get an User Returns one User after refreshing its Human or Agent classification and project ownership where supported. iMessage email identities retain their producer-observed classification and ownership because no current email ownership lookup is available. WhatsApp, WhatsApp Business and iMessage perform no provider fetch; only SMS Human classifications perform a phone number lookup. Current-project Agents expose resourceId; external-project Agents expose only pairwise managedBy. Conditional response evaluation uses the post-reconciliation representation. Stored reads use each platform definition; projection requires adapter support. |
| `PHOTON_MCP_GET_VOICE_LINE_PROFILE_ASSIGNMENT` | Getvoicelineprofileassignment | Get Voice line profile assignment Gets the explicit additional-profile override for an owned Voice-capable line. A line following the project default returns 200 without profileId. Requires platforms:read bound to the path project. |
| `PHOTON_MCP_GET_VOICE_PROFILE` | Getvoiceprofile | Get Voice profile Gets one reusable Voice profile, including its optional inbound delivery state. Requires platforms:read bound to the path project. |
| `PHOTON_MCP_GET_WEBHOOK_DESTINATION` | Getwebhookdestination | Get webhook destination Returns the configuration of one webhook destination belonging to the selected project. Missing or deleted destinations are reported as errors. This read does not disclose the signing secret returned when the destination or a secret rotation was created. |
| `PHOTON_MCP_GET_WEBHOOK_EVENT_SCHEMA` | Getwebhookeventschema | Get webhook event schema Returns the published reader JSON Schema for eventType in the requested webhook apiVersion. Use it to interpret events for that exact payload version. The response media type is application/schema+json; an authorized conditional request may return 304 without a body. Unsupported event/version combinations are rejected. |
| `PHOTON_MCP_GET_WHATSAPP_BUSINESS_ACCOUNT` | Getwhatsappbusinessaccount | Get WhatsApp Business account Gets the one WhatsApp Business Account this project has connected, with its number of live senders. Senders are resources and are listed by GET /platforms/resources?ability=whatsapp_business. The account is not a resource and carries no access token. Meta's retained numbers are listed separately by GET /platforms/whatsapp-business/account/phone-numbers. `subscribedAt` is absent until our app is attached to the account's webhooks. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_GET_WHATSAPP_SHARED_LINE_ASSIGNMENT` | Getwhatsappsharedlineassignment | Get WhatsApp shared line assignment Reads one WhatsApp shared line assignment. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LEAVE_ORGANIZATION` | Leaveorganization | Leave an organization; Owners must transfer or close first |
| `PHOTON_MCP_LIST_ACCOUNT_SERVICE_KEYS` | Listaccountservicekeys | List Account Service Keys Returns metadata for the authenticated account's unrevoked service keys, including expired keys, ordered newest first. Secret values are not returned; a key's credential is disclosed only when that key is created. |
| `PHOTON_MCP_LIST_ATTACHMENTS` | Listattachments | List attachments Lists the Project's Attachment metadata, with optional time filters. |
| `PHOTON_MCP_LIST_AUTHORIZED_APPLICATIONS` | Listauthorizedapplications | List connected applications Lists the OAuth applications authorized by the authenticated user. |
| `PHOTON_MCP_LIST_BILLING_PLANS` | Listbillingplans | List billing plans Lists the billing plan catalog, grouped by their public plan-metadata type. Use the returned plan information when choosing the category and planCode for a plan change. The catalog is the same for every project, and reading it does not purchase a plan. |
| `PHOTON_MCP_LIST_CREDIT_ACTIVITY` | Listcreditactivity | List credit activity Returns one page of how the selected organization's credit balance changed, newest first: credit notes issued and credit granted, credit applied to invoices, credit restored when the change an invoice paid for never applied, and credit voided. Each entry names the credit note (none for granted credit), the invoice when there is one, and the charge and subscription the credit note credits, or that the credit was a grant. Pass nextPage as page to read further. This operation does not change billing. |
| `PHOTON_MCP_LIST_EMAIL_RECOMMENDATIONS` | Listemailrecommendations | List email recommendations Reads Photon guidance from stored sending policies, sending setup and domain checks. Project and Organization restrictions repeat on each page of domain observations. Follow nextPageToken until hasMore is false; observations describe only the current page. Recommendations are advisory reads, never permission to send or resume. Reputation-rate guidance and supplementary delivery advice are explicitly unavailable until their sources are integrated. An empty list does not indicate healthy reputation or resolved findings. Requires platforms:read for the path Project. |
| `PHOTON_MCP_LIST_FILTERED_VERIFICATION_CODES` | Listfilteredverificationcodes | List filtered verification codes Lists the verification codes Photon kept from this project's dedicated lines and numbers. Inbound messages that carry a one-time code are filtered before delivery; this is the record that they arrived, so a quiet line can be told apart from a broken one. It records the receiving line, its platform and when the code arrived — never the code itself. Each entry names the dedicated line or number (`resourceId`) that received it. Newest first, within an optional inclusive `receivedAfter`/`receivedBefore` window. A page may hold fewer than `pageSize` entries and still return a `nextPageToken`; only its absence means the end. Filter by `platform`; to read one line, use its own filtered-otp path. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LIST_INVOICES` | Listinvoices | List invoices Returns one page of the selected organization's invoices, newest first: every invoice issued to it with a nonzero total or actual charges, including charges fully paid by credit; drafts and empty invoices are excluded. Each names what it charged the organization's own subscription and each project. Pass subject to list only the invoices that charge the organization itself or one of its projects, and nextCursor as cursor to read further. Listing invoices does not make a payment or modify a subscription. |
| `PHOTON_MCP_LIST_MESSAGES` | Listmessages | List Messages Lists the Project's Messages, with optional resource, conversation, and time filters. Results are eventually consistent. |
| `PHOTON_MCP_LIST_NUMBER_AREA_CODES` | Listnumberareacodes | List number area codes Lists current provider coverage for US local numbers, sorted and deduplicated. Coverage does not guarantee inventory carrying every required feature. New area-specific purchases must use a listed code; accepted purchases keep waiting if coverage later changes. Requires platforms:read for the path project. |
| `PHOTON_MCP_LIST_NUMBER_COUNTRIES` | Listnumbercountries | List number countries Lists supported purchase countries independently of current provider inventory. Requires platforms:read for the path project. |
| `PHOTON_MCP_LIST_OAUTH_SCOPES` | Listoauthscopes | List OAuth scopes Lists the business permissions available to OAuth applications. |
| `PHOTON_MCP_LIST_OPERATIONS` | Listoperations | List operations Lists the project's operations using the same operation representation as creation and GET. The API includes detail.setupUrl only with platforms:write for this project. Results are oldest first — every provision and release it has ever asked for, including the ones still running. This is the entire in-flight view: a resource only appears once it is real, so nothing half-built shows up in the resource list and nothing in flight is missing from this one. Filter by `resourceId` to get one resource's whole history, which for a pooled line is every tenure this project has had on it. `state` is comma-separated; `type` accepts one operation type and an absent filter means everything, including failed and cancelled operations. `endedAfter` keeps only operations that finished after that instant, so what failed or was withdrawn recently is one short page. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LIST_ORGANIZATION_MEMBERS` | Listorganizationmembers | List current organization members |
| `PHOTON_MCP_LIST_PROJECT_PLATFORMS` | Listprojectplatforms | List project platforms Lists the platform types available to this project. Every project currently sees the same fixed public contract, answered in-process rather than forwarded, so the list survives an outage of the private service. The project binding exists so that answer can narrow per project without moving the route. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LIST_PROJECTS` | Listprojects | List projects Returns a cursor-paginated page of the active projects in organizationId. Filter using query and the documented creation-time bounds, and navigate with pageSize and pageToken. Project roles are not returned and role is not a supported filter. |
| `PHOTON_MCP_LIST_PROJECT_SUBSCRIPTIONS` | Listprojectsubscriptions | List project subscriptions Lists the plan each of the selected project's categories holds, with its price and the payer's standing. It suits showing a project's plan wherever projects are listed; the billing overview adds billing periods, fixed charges, entitlements and usage. |
| `PHOTON_MCP_LIST_RESOURCE_FILTERED_VERIFICATION_CODES` | Listresourcefilteredverificationcodes | List a line's filtered verification codes Lists the verification codes Photon kept from one dedicated line or number. Inbound messages that carry a one-time code are filtered before delivery; this is the record that they arrived, so a quiet line can be told apart from a broken one. It records the receiving line, its platform and when the code arrived — never the code itself. Each entry names the dedicated line or number (`resourceId`) that received it. Newest first, within an optional inclusive `receivedAfter`/`receivedBefore` window. A page may hold fewer than `pageSize` entries and still return a `nextPageToken`; only its absence means the end. Answers 404 unless the project holds the resource now. Codes from an earlier tenure stay in the project-wide list. Filter by `platform` — a number receives both SMS and WhatsApp. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LIST_RESOURCES` | Listresources | List resources Lists the project's resources, oldest first, including retired ones unless `state` filters them out. Filter by `type`, by enabled `ability` and by comma-separated `state`. `detail` is a per-type public view. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LIST_SHARED_LINE_ASSIGNMENTS` | Listsharedlineassignments | List shared line assignments Lists the project's shared line assignments, oldest first. Released assignments are excluded unless includeReleased is set. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_LIST_SPACES` | Listspaces | List Spaces Lists the Project's stored Spaces, with optional participant and Message filters. Results are eventually consistent. |
| `PHOTON_MCP_LIST_USERS` | Listusers | List Users Lists stored Users without refreshing their classification; use Get User for current details. Message filters select incoming senders or outgoing recipients, excluding the Message's own endpoint. |
| `PHOTON_MCP_LIST_VOICE_PROFILES` | Listvoiceprofiles | List Voice profiles Lists reusable Voice profiles in this project. Requires platforms:read bound to the path project. |
| `PHOTON_MCP_LIST_WEBHOOK_API_VERSIONS` | Listwebhookapiversions | List webhook API versions Lists the published webhook payload API versions and their lifecycle metadata. The list is the same for every project. Use the selectable indicator when choosing a version for a destination. These payload dates are separate from SDK package versions. An authorized conditional request may return 304 without a response body. |
| `PHOTON_MCP_LIST_WEBHOOK_DESTINATIONS` | Listwebhookdestinations | List webhook destinations Returns a cursor-paginated page of active webhook destinations configured for the selected project. Use pageSize and pageToken to navigate it. The listing returns destination configuration, never signing secrets. |
| `PHOTON_MCP_LIST_WEBHOOK_EGRESS_ADDRESSES` | Listwebhookegressaddresses | List webhook egress addresses Returns the public network addresses from which this environment sends webhook deliveries. Use this information when configuring the receiving system's network allowlist. The result is environment-specific and does not describe the API service's ingress addresses. |
| `PHOTON_MCP_LIST_WEBHOOK_EVENT_TYPES` | Listwebhookeventtypes | List webhook event types Lists the webhook event types available in the requested apiVersion, including their descriptions, audiences and reader-schema URLs. Use this versioned catalog when selecting a destination's enabledEvents. The response may include version-retirement information; an authorized conditional request can return 304 without a body. |
| `PHOTON_MCP_LIST_WHATSAPP_ACCOUNT_PHONE_NUMBERS` | Listwhatsappaccountphonenumbers | List WhatsApp account phone numbers Lists the connected WABA's phone numbers directly from Meta, including numbers whose Photon sender was disconnected. Ownership is photon for a number in this project's current Photon inventory and meta otherwise. Match a Photon SMS number by its E.164 phoneNumber and reuse its existing displayName when reconnecting. A null name is unavailable, not permission to choose a new name. A failed lookup returns an error rather than an empty list. Requires platforms:read on the path project. |
| `PHOTON_MCP_LIST_WHATSAPP_SHARED_LINE_ASSIGNMENTS` | Listwhatsappsharedlineassignments | List WhatsApp shared line assignments Lists the project's WhatsApp shared line assignments, oldest first. Released assignments are excluded unless includeReleased is set. Requires the platforms:read permission bound to the project resource in the path. |
| `PHOTON_MCP_MARK_MESSAGE_READ` | Markmessageread | Mark a Message as read Persists a request to mark one incoming Message as read using its receiving account. A 202 means accepted for asynchronous execution, not handled by the provider. Requires Idempotency-Key. The returned action Message tracks its outcome; privacy settings may suppress remote visibility. |
| `PHOTON_MCP_PREVIEW_ORGANIZATION_CHANGE` | Previeworganizationchange | Preview an organization billing change Previews a fixed-charge quantity change on the selected organization's own subscription, such as SSO. Prices the change by the billing engine exactly as making it would bill it now: dueNow is that invoice, with taxes and the payer's credits applied. A purchase bills each unit it adds, even after a release this period. A release bills nothing; releasing a prorated charge credits its unused days to the organization's credit. dueLater is what the change leads to that is billed later instead, and nextCharge what is charged in advance at the next period start. change says what the change does by its kind: for a fixed-charge change, pass change.quote on with the purchase so it is refused if the price or period no longer hold. This operation does not change billing. |
| `PHOTON_MCP_PREVIEW_PROJECT_CHANGE` | Previewprojectchange | Preview a project billing change Previews a change on the selected project's subscription in the supplied category: a fixed-charge quantity change, or a plan change with the held fixed charges it carries over. Prices the change by the billing engine exactly as making it would bill it now: dueNow is that invoice, with taxes and the payer's credits applied. A purchase bills each unit it adds, even after a release this period. A release bills nothing; releasing a prorated charge credits its unused days to the organization's credit. dueLater is what the change leads to that is billed later instead, and nextCharge what is charged in advance at the next period start. change says what the change does by its kind: for a fixed-charge change, pass change.quote on with the purchase so it is refused if the price or period no longer hold. This operation does not change billing. An upgrade bills the replaced plan's usage to date and the new plan from now, less the replaced plan's unused time; change says when it applies and which held fixed charges the target does not sell: released first for a change that applies now, released with a downgrade when it applies. additions quotes what is added once an upgrade applies, each billed when it is added, in dueLater and outside dueNow. Supply both organizationId and projectId; the organization must pay for the project. |
| `PHOTON_MCP_PROVISION_IMESSAGE_DEDICATED_LINE` | Provisionimessagededicatedline | Provision dedicated iMessage line Claims one dedicated iMessage line for the project and enables iMessage on it. Always answers 202 with an operation: dedicated lines are allocated from available capacity, and unavailable capacity causes a wait rather than a failure — this can legitimately stay `running` for hours, which is exactly why the response is a handle to poll rather than a number. The project's messaging subscription must grant the dedicated iMessage lines entitlement (`imessage_dedicated_lines.can_purchase`), and that is checked before capacity is reserved. The line's own charge starts when a line is claimed; the subscription that grants the entitlement bills on its own terms, which cancelling a request does not change. Waiting requests are served first come, first served. One that is still waiting is cancelled with a `reason` if the project is deleted (`project_deleted`) or its plan stops selling dedicated lines (`entitlement_lost`); while the payer is restricted for overdue payment it keeps waiting. If you no longer want to wait, POST to the operation's cancel endpoint, which charges nothing for the line. The Idempotency-Key is required and permanent: repeating it returns the same operation forever. A further line always needs a NEW key, including while others are still waiting. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_PROVISION_WHATSAPP_DEDICATED_LINE` | Provisionwhatsappdedicatedline | Provision dedicated WhatsApp line Provisions one dedicated WhatsApp line with WhatsApp and shared Voice enabled. It attaches to an eligible iMessage line the project already owns when possible so both products keep the same number; otherwise it claims healthy, available WhatsApp-capable dedicated-line inventory. Always answers 202, because waiting when no inventory is available is not a failure. The product opens its own charge period after the abilities are enabled; Voice has no separate charge. Waiting requests are served first come, first served, and are cancelled with a `reason` exactly as for a dedicated iMessage line. Cancel the returned operation to stop waiting. The Idempotency-Key is required and permanent. |
| `PHOTON_MCP_PURCHASE_SMS_NUMBER` | Purchasesmsnumber | Purchase SMS number Buys one US local number from the provider and records it as a resource with SMS enabled. Requires countryCode (US) and accepts an optional three-digit geographic areaCode. The server selects an exact matching number. Empty inventory keeps the operation running until a number is available or the caller cancels before ordering begins. Always answers 202 with an operation: the work runs behind the response, and the Location points at the operation to poll. New area-specific requests must appear in current provider coverage; discover it with GET /sms/numbers/area-codes?countryCode=US. Coverage and subscription checks run before operation creation. Billing follows delivery. Replays return the original operation without checking current coverage. The Idempotency-Key is required and permanent: repeating it returns the same operation forever, never a second number. A further number always needs a NEW key, including while others are still running. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_QUERY_MESSAGE_METRICS` | Querymessagemetrics | Query metrics Runs read-only SQL over the Project's message_events or call_events table. Get the SQL schema for supported columns, capabilities, and limits. |
| `PHOTON_MCP_RELEASE_IMESSAGE_DEDICATED_LINE` | Releaseimessagededicatedline | Release dedicated iMessage line Removes only iMessage from one dedicated line. Shared Voice is removed only when WhatsApp is absent; if WhatsApp remains, Voice, the resource, ownership, and phone number are preserved. Usually finishes inside this request and answers 200; a slow workflow answers 202 with an operation to poll. Takes no Idempotency-Key because the open iMessage charge period identifies this product tenure. |
| `PHOTON_MCP_RELEASE_RESOURCE` | Releaseresource | Release resource Gives one resource back, whatever it is. What that means is the resource's own business: an SMS number goes back to the provider and is retired, a dedicated iMessage line goes back to the shared pool and stays in existence for someone else to claim. Either way the provider is contacted first where there is one, then a single transaction disables every ability, ends the project's hold and closes the charge period — so a provider that refuses leaves the resource exactly as it was, still owned and still billed. Usually finishes inside this request and answers 200; if the provider is slow it answers 202 and the Location points at the operation to poll. The decrement runs behind the answer either way, so the resource is gone when you are told it is. Takes no Idempotency-Key — releasing the same resource twice is the same request. Releasing one that is already gone answers 404. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_RELEASE_SHARED_LINE_ASSIGNMENT` | Releasesharedlineassignment | Release shared line assignment Releases a shared line assignment, freeing both its seat and its handle for reassignment. The row is retained for audit and returned with releasedAt set, so repeating the call is safe. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_RELEASE_WHATSAPP_DEDICATED_LINE` | Releasewhatsappdedicatedline | Release dedicated WhatsApp line Removes only WhatsApp from one dedicated line. Shared Voice is removed only when iMessage is absent; if iMessage remains, Voice, the resource, ownership, and phone number are preserved. Usually finishes inside this request and answers 200; a slow workflow answers 202 with an operation to poll. Takes no Idempotency-Key because the open WhatsApp charge period identifies this product tenure. |
| `PHOTON_MCP_RELEASE_WHATSAPP_SHARED_LINE_ASSIGNMENT` | Releasewhatsappsharedlineassignment | Release WhatsApp shared line assignment Releases a WhatsApp shared line assignment, freeing its seat for reassignment. The row is retained for audit and returned with releasedAt set, so repeating the call is safe. Requires the platforms:write permission bound to the project resource in the path. |
| `PHOTON_MCP_RESET_ACCOUNT_PROFILE_PICTURE` | Resetaccountprofilepicture | Remove profile picture Removes the authenticated account's custom profile picture and returns the account using its default picture. This operation does not upload a replacement; use the upload-and-commit operations when setting a new custom picture. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_RESET_AGENT_PROFILE_AVATAR` | Resetagentprofileavatar | Reset agent avatar Replaces the selected project's agent avatar with the project's default avatar, a generated planet image derived from the project ID, and returns the updated agent profile. The reset does not restore an earlier avatar: a custom avatar it replaces is discarded and must be uploaded and committed again to use it. When the default avatar is already in use, the profile is returned unchanged. This does not change the account's personal profile picture. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_REVOKE_ACCOUNT_SERVICE_KEY` | Revokeaccountservicekey | Revoke Account Service Key Revokes the account-owned service key identified by serviceKeyId and returns its revoked metadata. Repeating the revocation is stable. Revocation changes the credential's validity; it does not create a replacement key. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_REVOKE_AUTHORIZED_APPLICATION` | Revokeauthorizedapplication | Revoke connected application Revokes the authenticated user's grant for one OAuth application. |
| `PHOTON_MCP_SEND_MESSAGE` | Sendmessage | Send a Message Sends SMS, email, WhatsApp Personal, WhatsApp Business, iMessage, or Telegram text and image messages. A shared iMessage line sends only in direct Spaces, only to a peer with an active Assignment who has messaged it since that Assignment. SMS and MMS require current Platforms authorization for the sender and every recipient; campaign eligibility is required unless every recipient is in-network. |
| `PHOTON_MCP_SET_SPACE_TYPING` | Setspacetyping | Set typing in a Space Saves one transient typing update as an authorized Agent in this Space. Returns the dispatched Message with HTTP 202. Successful provider handoff ends in accepted; rejection or expiry ends in failed. Repeat true to refresh; false stops where supported. Callers control refreshes. Unsupported platforms return OPERATION_UNAVAILABLE. |
| `PHOTON_MCP_UNASSIGN_SMS_LINE_CAMPAIGN` | Unassignsmslinecampaign | Unassign SMS line campaign Any project writer, including a scoped API key, may detach the campaign. The number and campaign remain owned. Requires a permanent Idempotency-Key and expectedVersion. Local eligibility is blocked immediately; provider detachment runs asynchronously. |
| `PHOTON_MCP_UNASSIGN_VOICE_LINE_PROFILE` | Unassignvoicelineprofile | Unassign Voice line profile Removes a line's explicit override when the resource version matches so the line follows the project default. Profiles and the pstn_voice ability are unchanged. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_UPDATE_ACCOUNT` | Updateaccount | Update account Updates the supplied firstName and lastName fields on the authenticated account and returns the updated profile. Only the documented profile fields can be changed through this endpoint; profile-picture uploads and phone-number verification use their dedicated operations. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_UPDATE_AGENT_PROFILE` | Updateagentprofile | Update agent profile Updates the supplied firstName and lastName fields in the project's agent profile and returns the updated profile. Avatar upload, commit and reset are separate operations. The caller must be authorized to change configuration for the selected project. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_UPDATE_DEFAULT_VOICE_PROFILE` | Updatedefaultvoiceprofile | Update default Voice profile Patches the default profile's protocol or mediaEncryption when expectedVersion matches. Omitted fields are preserved. Its server-assigned name is immutable, and directional configuration uses the profileId returned by this resource. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_UPDATE_PROJECT` | Updateproject | Update project Updates the identified project's name and returns the updated project. The project slug is not a mutable field in this request. Use an authorized account or organization service-identity credential; a project API key is not accepted. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_UPDATE_VOICE_PROFILE` | Updatevoiceprofile | Update Voice profile Patches an additional profile's name, protocol, or mediaEncryption when expectedVersion matches. Omitted fields are preserved. Directional configuration is managed through the profile's inbound and outbound endpoints. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_UPDATE_VOICE_PROFILE_OUTBOUND_AUTHENTICATION` | Updatevoiceprofileoutboundauthentication | Update Voice outbound authentication Changes a SIP profile's outbound Digest algorithm when expectedVersion matches. The profileId may identify the default or an additional profile. This policy-only change preserves the password, username, and any previous-password grace deadline. SHA-256 is recommended; MD5 is a weaker legacy option. Returns non-secret outbound metadata and the profile version. Requires platforms:write bound to the path project. |
| `PHOTON_MCP_UPDATE_WEBHOOK_DESTINATION` | Updatewebhookdestination | Update webhook destination Updates the supplied URL, name, description, status or enabledEvents fields on a project's webhook destination and returns its updated configuration. The payload API version is not a mutable field in this request. Event selections are checked against the destination's versioned catalog; signing-secret rotation is a separate operation. Supply the required Idempotency-Key header. |
| `PHOTON_MCP_VERIFY_TOTP_ENROLLMENT` | Verifytotpenrollment | Verify TOTP enrollment Requires a first-party interactive Account credential authenticated no more than 300 seconds ago. |

## Supported Triggers

None listed.

## Installation and MCP Setup

### Path 1: SDK Installation

#### Path 1, Step 1: Install Composio

Install the Composio SDK, the OpenAI provider, and the OpenAI SDK
```python
pip install composio composio_openai openai
```

```typescript
npm install @composio/core @composio/openai openai
```

#### Path 1, Step 2: Create a Composio session

Initialize Composio with the OpenAI Responses provider and create a session scoped to Photon MCP
```python
import json
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIResponsesProvider

composio = Composio(provider=OpenAIResponsesProvider())
client = OpenAI()

session = composio.create(user_id="your-user-id", toolkits=["photon_mcp"])
tools = session.tools()
```

```typescript
import OpenAI from "openai";
import { Composio } from "@composio/core";
import { OpenAIResponsesProvider } from "@composio/openai";

const composio = new Composio({ provider: new OpenAIResponsesProvider() });
const client = new OpenAI();

const session = await composio.create("your-user-id", { toolkits: ["photon_mcp"] });
const tools = await session.tools();
```

#### Path 1, Step 3: Run Photon MCP tools with your agent

Send a request, execute the Photon MCP tool calls through the session, and print the final answer
```python
response = client.responses.create(
    model="gpt-5.6-sol",
    tools=tools,
    input=[{"role": "user", "content": "List all conversations in my Photon project"}],
)

while True:
    tool_calls = [o for o in response.output if o.type == "function_call"]
    if not tool_calls:
        break
    results = composio.provider.handle_tool_calls(response=response, session=session)
    response = client.responses.create(
        model="gpt-5.6-sol",
        tools=tools,
        previous_response_id=response.id,
        input=[
            {"type": "function_call_output", "call_id": call.call_id, "output": json.dumps(results[i])}
            for i, call in enumerate(tool_calls)
        ],
    )

print(response.output_text)
```

```typescript
let response = await client.responses.create({
  model: "gpt-5.6-sol",
  tools,
  input: [{ role: "user", content: "List all conversations in my Photon project" }],
});

while (response.output.some((o) => o.type === "function_call")) {
  const outputs = await composio.provider.handleToolCalls(session, response.output);
  response = await client.responses.create({
    model: "gpt-5.6-sol",
    tools,
    previous_response_id: response.id,
    input: outputs,
  });
}

console.log(response.output_text);
```

### Path 2: MCP Server Setup

#### Path 2, Step 1: Install Composio

Install the Composio SDK and your agent framework
```python
pip install composio claude-agent-sdk
```

```typescript
npm install @composio/core ai @ai-sdk/mcp @ai-sdk/openai
```

#### Path 2, Step 2: Create a session with MCP enabled

Create a session scoped to Photon MCP and read its MCP URL and headers
```python
from composio import Composio

composio = Composio()
session = composio.create(user_id="your-user-id", toolkits=["photon_mcp"], mcp=True)
```

```typescript
import { Composio } from "@composio/core";

const composio = new Composio();
const { mcp } = await composio.create("your-user-id", {
  toolkits: ["photon_mcp"],
  mcp: true,
});
```

#### Path 2, Step 3: Connect your agent to the MCP server

Pass the session's MCP URL and headers to your agent and run a Photon MCP request
```python
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock

options = ClaudeAgentOptions(
    mcp_servers={
        "composio": {
            "type": "http",
            "url": session.mcp.url,
            "headers": session.mcp.headers,
        }
    },
    system_prompt="You are a helpful assistant with access to Photon MCP tools.",
    tools=[],
    allowed_tools=["mcp__composio__*"],
)

async def main():
    async with ClaudeSDKClient(options=options) as client:
        await client.query("List all conversations in my Photon project")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

asyncio.run(main())
```

```typescript
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";

const client = await createMCPClient({
  transport: { type: "http", url: mcp.url, headers: mcp.headers },
});

const { text } = await generateText({
  model: openai("gpt-5.6-sol"),
  tools: await client.tools(),
  prompt: "List all conversations in my Photon project",
  stopWhen: stepCountIs(10),
});

console.log(text);
await client.close();
```

## Why Use Composio?

### 1. AI Native Photon MCP Integration

- Supports both Photon MCP and direct API based integrations
- Structured, LLM-friendly schemas for reliable tool execution
- Rich coverage for reading, writing, and querying your Photon MCP data

### 2. Managed Auth

- Connects Photon MCP through DCR OAuth without hard-coded credentials
- Central place to manage, scope, and revoke Photon MCP access
- Per user and per environment credentials instead of hard-coded keys

### 3. Agent Optimized Design

- Tools are tuned using real error and success rates to improve reliability over time
- Comprehensive execution logs so you always know what ran, when, and on whose behalf

### 4. Enterprise Grade Security

- Fine-grained RBAC so you control which agents and users can access Photon MCP
- Scoped, least privilege access to Photon MCP resources
- Full audit trail of agent actions to support review and compliance

## Use Photon MCP with any AI Agent Framework

Choose a framework you want to connect Photon MCP with:

- [ChatGPT](https://composio.dev/toolkits/photon_mcp/framework/chatgpt)
- [Claude Cowork](https://composio.dev/toolkits/photon_mcp/framework/claude-cowork)
- [Hermes](https://composio.dev/toolkits/photon_mcp/framework/hermes-agent)
- [Atomic Agent](https://composio.dev/toolkits/photon_mcp/framework/atomic-agent)

## Related Toolkits

- [Gmail](https://composio.dev/toolkits/gmail) - Gmail is Google's email service with powerful spam protection, search, and G Suite integration. It keeps your inbox organized and makes communication fast and reliable.
- [Outlook](https://composio.dev/toolkits/outlook) - Outlook is Microsoft's email and calendaring platform for unified communications and scheduling. It helps users stay organized with powerful email, contacts, and calendar management.
- [Slack](https://composio.dev/toolkits/slack) - Slack is a channel-based messaging platform for teams and organizations. It helps people collaborate in real time, share files, and connect all their tools in one place.
- [Gong](https://composio.dev/toolkits/gong) - Gong is a platform for video meetings, call recording, and team collaboration. It helps teams capture conversations, analyze calls, and turn insights into action.
- [Microsoft teams](https://composio.dev/toolkits/microsoft_teams) - Microsoft Teams is a collaboration platform that combines chat, meetings, and file sharing within Microsoft 365. It keeps distributed teams connected and productive through seamless virtual communication.
- [Slackbot](https://composio.dev/toolkits/slackbot) - Slackbot is a conversational automation tool for Slack that handles reminders, notifications, and automated responses. It boosts team productivity by streamlining onboarding, answering FAQs, and managing timely alerts—all right inside Slack.
- [2chat](https://composio.dev/toolkits/_2chat) - 2chat is an API platform for WhatsApp and multichannel text messaging. It streamlines chat automation, group management, and real-time messaging for developers.
- [Agent mail](https://composio.dev/toolkits/agent_mail) - Agent mail provides AI agents with dedicated email inboxes for sending, receiving, and managing emails. It empowers agents to communicate autonomously with people, services, and other agents—no human intervention needed.
- [Aircall](https://composio.dev/toolkits/aircall) - Aircall is a cloud-based phone and call-center platform for business communications. It centralizes calls, contacts, teams, numbers, and tags in one place.
- [Android Texter](https://composio.dev/toolkits/android_texter) - Android Texter is an API service that connects Android phones to SMS, MMS, contacts, and device data. Use it to automate mobile messaging without building your own phone-to-API bridge.
- [Basecamp](https://composio.dev/toolkits/basecamp) - Basecamp is a project management and team collaboration tool by 37signals. It helps teams organize tasks, share files, and communicate efficiently in one place.
- [Blooio](https://composio.dev/toolkits/blooio) - Blooio is a stable v2 API platform for messaging, chats, contacts, groups, phone numbers, and account analytics. It gives teams a clean way to build reliable communication workflows without stitching together fragile custom APIs.
- [Callback24](https://composio.dev/toolkits/callback24) - Callback24 is a telephony API for managing phone calls, users, services, and routing groups. It centralizes call control and routing to automate voice workflows and operations.
- [CallOnTheGo](https://composio.dev/toolkits/callonthego) - CallOnTheGo is a telephony API for managing phone numbers, caller IDs, suppression lists, audio assets, contact lists, and Voice AI campaigns. It provides programmatic control over calling infrastructure and campaign automation for scalable voice outreach.
- [Carbon Voice MCP](https://composio.dev/toolkits/carbon_voice_mcp) - Carbon Voice MCP is a voice-first collaboration platform for messages, conversations, and workflows. Use it to centralize voice communications and streamline team collaboration.
- [CardClan](https://composio.dev/toolkits/cardclan) - CardClan is a digital card platform for creating and sending personalized team cards. Use it to celebrate moments, share card links, and manage card workflows without extra coordination.
- [Chatwork](https://composio.dev/toolkits/chatwork) - Chatwork is a team communication platform with group chats, file sharing, and task management. It helps businesses boost collaboration and streamline productivity.
- [Clickmeeting](https://composio.dev/toolkits/clickmeeting) - ClickMeeting is a cloud-based platform for running online meetings and webinars. It helps businesses and individuals host, manage, and engage virtual audiences with ease.
- [Daily](https://composio.dev/toolkits/daily) - Daily is a WebRTC video and audio API platform for building rooms, meetings, recordings, live streams, transcriptions, and telephony. It gives developers reliable real-time media infrastructure without managing complex conferencing stacks.
- [Dailybot](https://composio.dev/toolkits/dailybot) - DailyBot streamlines team collaboration with chat-based standups, reminders, and polls. It keeps work flowing smoothly in your favorite messaging platforms.

## Frequently Asked Questions

### Do I need my own developer credentials to use Photon MCP with Composio?

Yes, Photon MCP requires you to configure your own Dcr OAuth credentials. Once set up, Composio handles secure credential storage and management for you.

### Can I use multiple toolkits together?

Yes! Composio's Tool Router enables agents to use multiple toolkits. [Learn more](https://docs.composio.dev/tool-router/overview).

### Is Composio secure?

Composio is SOC 2 and ISO 27001 compliant with all data encrypted in transit and at rest. [Learn more](https://trust.composio.dev).

### What if the API changes?

Composio maintains and updates all toolkit integrations automatically, so your agents always work with the latest API versions.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)