MCP#
Photon supports Model Context Protocol (MCP) for connecting MCP-compatible AI clients to Photon testing data and operations.
MCP clients interact with Photon using the permissions of the authenticated user.
Prerequisites#
To connect an MCP client, you need:
- An active Photon account
- Access to the required project
- An access token
- An MCP client from the list below, or another client that can send custom HTTP headers to a remote MCP server
Access tokens are managed in Settings → Personal → Access Tokens. See Access Tokens.
Access tokens should not be included in prompts, source code, or shared configuration files.
Endpoint and Authentication#
Photon MCP uses the Streamable HTTP transport. The endpoint is https://<workspace>.photontest.com/api/mcp.
Every request must include two HTTP headers:
| Header | Value |
|---|---|
X-Photon-Username |
Your Photon username or email |
X-Photon-Api-Token |
An access token from Settings → Personal → Access Tokens |
Requests without these headers, including the initial connection, are rejected with HTTP 401. Photon MCP does not use OAuth sign-in, so a client that can authenticate only through OAuth cannot connect.
The examples on this page read both values from the PHOTON_USERNAME and PHOTON_API_TOKEN environment variables, so the token is not stored in the configuration file:
Restart the client after setting the variables. An application started from the desktop may not see variables defined in a shell profile; if the client cannot connect, start it from a terminal where the variables are set.
Connecting an MCP Client#
In the examples, replace <workspace> with your workspace name.
| Client | Connection |
|---|---|
| Claude Code | Direct |
| Claude Desktop | Through the mcp-remote bridge |
| ChatGPT | Desktop app through the Codex configuration; web not supported |
| Codex | Direct |
| Cursor | Direct |
| VS Code (GitHub Copilot) | Direct |
| Devin Desktop (Windsurf) | Direct |
| Gemini CLI | Direct |
After the connection is established, the client discovers the Photon MCP tools available to the authenticated user.
Claude Code#
Add the server for all your projects:
claude mcp add --transport http --scope user photon https://<workspace>.photontest.com/api/mcp \
--header 'X-Photon-Username: ${PHOTON_USERNAME}' \
--header 'X-Photon-Api-Token: ${PHOTON_API_TOKEN}'
The single quotes keep the variable references in the configuration; Claude Code substitutes the values when it connects. Run /mcp in Claude Code to check the connection.
To share the server with a team, add it to .mcp.json in the project root instead. Each team member sets their own environment variables:
{
"mcpServers": {
"photon": {
"type": "http",
"url": "https://<workspace>.photontest.com/api/mcp",
"headers": {
"X-Photon-Username": "${PHOTON_USERNAME}",
"X-Photon-Api-Token": "${PHOTON_API_TOKEN}"
}
}
}
}
Claude Desktop#
Custom connectors added by URL in Claude Desktop and on claude.ai can send only header names approved by Anthropic, so they cannot connect to Photon MCP. Claude Desktop connects through mcp-remote, a bridge that runs on your computer and adds the headers to every request. It requires Node.js.
- In the Claude menu of the system menu bar, open Settings…, select Developer, and click Edit Config.
-
Add the Photon server to
claude_desktop_config.json:{ "mcpServers": { "photon": { "command": "npx", "args": [ "-y", "mcp-remote", "https://<workspace>.photontest.com/api/mcp", "--header", "X-Photon-Username:${PHOTON_USERNAME}", "--header", "X-Photon-Api-Token:${PHOTON_API_TOKEN}" ], "env": { "PHOTON_USERNAME": "<username>", "PHOTON_API_TOKEN": "<access-token>" } } } } -
Quit Claude Desktop completely and start it again.
Keep the header arguments without spaces around :. The file contains your access token: do not share it.
ChatGPT#
- ChatGPT desktop app shares its MCP configuration with Codex. Configure Photon as described in Codex.
- ChatGPT on the web is not supported: custom MCP servers added there can authenticate only through OAuth or without authentication.
Codex#
Codex CLI, the Codex IDE extension, and the ChatGPT desktop app read MCP servers from ~/.codex/config.toml. Add:
[mcp_servers.photon]
url = "https://<workspace>.photontest.com/api/mcp"
env_http_headers = { "X-Photon-Username" = "PHOTON_USERNAME", "X-Photon-Api-Token" = "PHOTON_API_TOKEN" }
env_http_headers maps each header to the name of the environment variable that holds its value. Run codex mcp list to check that the server is configured.
Cursor#
Add the server to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json in a project:
{
"mcpServers": {
"photon": {
"url": "https://<workspace>.photontest.com/api/mcp",
"headers": {
"X-Photon-Username": "${env:PHOTON_USERNAME}",
"X-Photon-Api-Token": "${env:PHOTON_API_TOKEN}"
}
}
}
}
VS Code (GitHub Copilot)#
Add the server to ~/.copilot/mcp-config.json for all workspaces, or to .mcp.json in the workspace root:
{
"mcpServers": {
"photon": {
"type": "http",
"url": "https://<workspace>.photontest.com/api/mcp",
"headers": {
"X-Photon-Username": "${PHOTON_USERNAME}",
"X-Photon-Api-Token": "${PHOTON_API_TOKEN}"
},
"tools": ["*"]
}
}
}
The same file is available from the Command Palette: run Chat: Open Customizations, select MCP Servers, then Add Server, and choose Global > Copilot Global. Use the braced ${NAME} form for the variables.
Devin Desktop (Windsurf)#
Devin Desktop is the new name of Windsurf. It does not document environment variable references in headers, so the values are entered directly. Add the server to your user configuration, ~/.config/devin/mcp_config.json (on Windows, %APPDATA%\devin\mcp_config.json):
{
"mcpServers": {
"photon": {
"url": "https://<workspace>.photontest.com/api/mcp",
"transport": "http",
"headers": {
"X-Photon-Username": "<username>",
"X-Photon-Api-Token": "<access-token>"
}
}
}
}
To open the file, click Customize in the agent sidebar, open the MCPs tab, and select This computer under Install MCPs for. Do not put the token in a project's .devin/mcp_config.json, which is shared through version control; use the user configuration or .devin/mcp_config.local.json.
Gemini CLI#
Add the server for all your projects:
gemini mcp add --scope user --transport http \
--header 'X-Photon-Username: ${PHOTON_USERNAME}' \
--header 'X-Photon-Api-Token: ${PHOTON_API_TOKEN}' \
photon https://<workspace>.photontest.com/api/mcp
Gemini CLI stores the server in ~/.gemini/settings.json and resolves the variable references when it loads the settings. Run /mcp in Gemini CLI to check the connection.
What the Client Receives#
After connecting, the client receives:
- Tools — the operations listed below. Only the tools available in your workspace plan and allowed by your project permissions are offered.
- Prompts — ready-made workflows for common tasks. Clients usually show them as commands or templates.
- Instructions — guidance that helps the AI model use Photon tools correctly.
Available Operations#
Depending on the workspace plan and user permissions, operations may include:
- Projects — retrieve project information
- Test repository — retrieve, create, and update cases, test suites, and shared steps
- Runs — retrieve, create, and update runs
- Milestones — work with milestones
- Environments — work with environments
- Executions — access results, tests, logs, screenshots, comments, and issues
- Photon Agent — work with Photon Agent launches
- Files — work with related files
Using Photon Through MCP#
After configuration, Photon operations can be requested from an MCP-compatible client using natural-language instructions.
Examples:
Show the cases in the Login suite.
Find failed tests from the latest execution.
Create a case for password reset.
Show the execution logs for failed tests.
List the open runs in this project.
The MCP client maps the request to the corresponding Photon MCP operation.
Troubleshooting#
- HTTP 401 — the client did not send
X-Photon-UsernameandX-Photon-Api-Token, or their values are wrong. Check that the environment variables are visible to the client, that the token has not expired or been deleted, and that the username or email belongs to the token owner. - Some tools are missing — the tools depend on the workspace plan and on your project permissions.
Permissions and Security#
MCP access follows Photon user and project permissions.
Users can access only the projects, data, and operations available to their accounts. Operations that modify Photon data require the corresponding project permissions.
Access tokens should be revoked or replaced when they are no longer required or if they have been exposed.