MCP Integration

This guide explains how to connect an MCP client to Testifly, how authentication works, and which tools are available after connection.

1. Endpoint

Use this MCP URL:

https://mcp.testifly.dev/mcp

The endpoint is exposed over HTTPS and expects MCP requests on the /mcp path.

2. Authentication

Testifly MCP uses Bearer authentication and supports both API key tokens and OAuth access tokens.

Option A: API key token

Build the bearer token in this format:

<projectId>.<apiKey>

Send it in the Authorization header:

Authorization: Bearer <projectId>.<apiKey>

Where to get the values:

1. Open your project in Testifly.
2. Go to Settings.
3. Open API Keys.
4. Create or copy an API key.
5. Use your project id together with that API key to build the bearer token.

Option B: OAuth access token

If you connect with OAuth, your MCP tool (Claude, Codex, ChatGPT, and similar clients) handles sign-in and token management for you.

3. Connection steps

1. Open your MCP client configuration.
2. Add a new remote MCP server.
3. Set the server URL to https://mcp.testifly.dev/mcp.
4. Add authentication:
   • API key mode: Authorization: Bearer <projectId>.<apiKey>
   • OAuth mode: complete sign-in in your MCP client (it usually adds the header automatically)
5. Save the configuration and reconnect the client.

4. Example configuration

The exact format depends on your MCP client.

API key example:

{
  "url": "https://mcp.testifly.dev/mcp",
  "headers": {
    "Authorization": "Bearer <projectId>.<apiKey>"
  }
}

OAuth example:

{
  "url": "https://mcp.testifly.dev/mcp",
  "auth": "oauth"
}

If your client asks for a token value directly:

<projectId>.<apiKey>
<oauthAccessToken>

Most OAuth-enabled MCP clients fill this in automatically after sign-in.

5. Available tools

After connecting successfully, the Testifly MCP server exposes these tools:

Read tools

• getFeatureDetails - Get the overview and definition of a feature in the project.
• getTestsByFeatureId - Get the tests that belong to one feature.
• getAllTests - Get all tests in the project, optionally filtered by keywords.
• getTestDetails - Get the full details of one test.
• getFeatureUIComponents - Get the UI components of a feature.
• getUIComponentsSummaryByFeature - Get a smaller UI component summary for a feature.
• getTestRunsAndResults - Get the execution history and results of a test.
• getTestSuites - Get the test suites of the project.

Write tools

• createTests - Create new tests in the project.
• editTest - Update an existing test.
• editFeature - Update a feature overview or definition.

6. Additional MCP capabilities

In addition to tools, the server also provides:

• A prompt named must_use_prompt
• A read-only resource named testifly://test_features/public

7. Troubleshooting

401 Unauthorized

Check all of the following:

1. The header starts with Bearer.
2. There are no extra spaces before or after the token.
3. If using API key auth, the API key is valid.
4. If using API key auth, the project id is correct.
5. If using API key auth, the token format is exactly <projectId>.<apiKey>.
6. If using OAuth, sign out and sign back in from your MCP client.
7. If using OAuth, make sure you approved the requested permissions.