Connect via MCP

Certyn exposes a remote MCP server over Streamable HTTP so external MCP clients can connect directly to your Certyn workspace.

Server URL

For Certyn Cloud, the MCP endpoint is:

https://api.certyn.io/api/mcp

The public manifest is available at:

https://certyn.io/server.json

Authentication

Two ways in, and the difference matters for what an agent can do once connected.

Sign in with your Certyn account (recommended). The client runs an OAuth/OIDC flow against Auth0 and holds a user session. This is what every example below uses.

Send an API key header. Works with any client that can set a header, and is the fallback when OAuth is not available. Create the key in Settings → API Keys.

The difference: an API-key connection is scope-limited and, by design, cannot create API keys. So an agent setting up CI over an API-key connection has to stop and ask you to create the pipeline key by hand, while a signed-in connection can do it itself with create_ci_api_key.

Pick the right scopes for an API key

A signed-in connection carries your own permissions, so every tool is available. An API key carries only its scopes, and a tool the key cannot reach is left out of the tool list entirely. The agent never sees it, so it cannot tell you it lacks permission. It simply behaves as though Certyn does not support what you asked for.

This matters most for setup. Creating projects and environments, setting variables, writing the wiki and creating processes all sit behind platform:manage:

If you want the typical setup flow below, choose MCP Setup. Otherwise create_project and friends will be missing and the agent will not know why.

Demo tokens are not supported on either path.

When an unauthenticated client hits the MCP endpoint, Certyn returns the OAuth protected-resource metadata needed for authorization server discovery.

Pre-registered OAuth clients

Use Certyn's pre-registered public OAuth client when your MCP client lets you provide a client ID. These clients use Authorization Code with PKCE and do not have a client secret.

Requested OAuth scopes:

openid profile email offline_access mcp

Claude Code

Claude Code registers its own OAuth client unless you give it one, so pass Certyn's client ID and a fixed callback port. The port must match a redirect URI Certyn has registered; 8080 is the default, with 8090 and 8123 available if that port is already in use on your machine.

claude mcp add --transport http certyn https://api.certyn.io/api/mcp \
  --client-id tpc_nZvCVz9Wdh1yb7VX7VBzi4 \
  --callback-port 8080

Then run /mcp inside Claude Code and complete the browser sign-in. Requires Claude Code v2.1.191 or later for --client-id and --callback-port.

To share the configuration with a team, commit .mcp.json to the repository. Everyone who clones it connects by running /mcp and signing in as themselves:

{
  "mcpServers": {
    "certyn": {
      "type": "http",
      "url": "https://api.certyn.io/api/mcp",
      "oauth": { "clientId": "tpc_nZvCVz9Wdh1yb7VX7VBzi4", "callbackPort": 8080 }
    }
  }
}

A Certyn connector added in claude.ai also appears in Claude Code automatically, provided you are signed in to Claude Code with a claude.ai account.

Claude

Create a custom connector in Claude with the following values:

MCP server URL: https://api.certyn.io/api/mcp
OAuth Client ID: tpc_nZvCVz9Wdh1yb7VX7VBzi4
OAuth Client Secret: leave empty

The client is registered for both Claude callback domains:

https://claude.ai/api/mcp/auth_callback
https://claude.com/api/mcp/auth_callback

ChatGPT

Use the following client only when ChatGPT shows this exact callback URL in the connector settings:

Callback URL: https://chatgpt.com/connector/oauth/qe61i3KmIVPC
MCP server URL: https://api.certyn.io/api/mcp
OAuth Client ID: tpc_nKin1n5FA7aLTSJjF5N846
OAuth Client Secret: leave empty

ChatGPT callback IDs are workspace-connector specific. If ChatGPT displays a different callback URL, this client ID will not work; that callback must be registered separately.

Cursor

Add Certyn to your user or project mcp.json:

{
  "mcpServers": {
    "certyn": {
      "url": "https://api.certyn.io/api/mcp",
      "auth": {
        "CLIENT_ID": "tpc_jZgoggfpgCQ6q2ZwHeEr2B",
        "scopes": ["openid", "profile", "email", "offline_access", "mcp"]
      }
    }
  }
}

The Cursor client accepts the current desktop, hosted, and legacy callback forms. No CLIENT_SECRET is required.

Providing these client IDs avoids creating a new Auth0 application every time a connector is disconnected and reconnected. Dynamic Client Registration remains available as a fallback for other MCP clients.

Capability model

MCP v1 is tenant-wide.

• One MCP connection can access any project or environment your user can already access.
• Project tools accept projectIdOrSlug when context matters.
• Tools are direct project-record calls. ask_certyn is the one exception: it takes an open-ended question and returns a reasoned answer built from the project's own data.
• MCP resources are not exposed in v1.

Prompts

The server also advertises five prompts, which most clients surface as slash commands. They are starting points for common jobs rather than extra capability:

Supported tools

The server exposes 55 tools in eleven groups. They write as well as read.

See the MCP Tool Catalog for every tool's arguments.

Typical setup flow

From an empty account, the whole thing can be done over MCP without opening the app.

1. Add the Certyn MCP server in your client and complete the sign-in.
2. whoami — confirm which workspace you are in. One account can own several, and project names are not unique across them.
3. create_project — pass baseUrl. A project created without one sits on a placeholder URL and no run will do anything useful.
4. add_env_var — credentials for the app under test: LOGIN_USERNAME, LOGIN_PASSWORD, AUTH_MODE. Secret values are masked wherever they are read back.
5. update_wiki — what the product does, what matters, and what a run must never touch. This text is injected into the system prompt of every run in the project, so it changes run quality more than anything else here.
6. create_test_cases_batch — natural-language instructions with tags, not scripts.
7. create_process — group cases by tag, then get_process to check what it resolves to. A process matching zero cases looks identical to a working one until it runs and does nothing.
8. run_process, then wait_for_process_run. Do not poll in a loop; the wait tools block and return the result, and on timeout you call them again.
9. get_execution_detail for outcome, summary, and evidence. get_execution_transcript when the summary is not enough.

To wire it into CI, add get_ci_setup for the configuration and create_ci_api_key for the pipeline credential, then list_ci_runs to confirm the first run actually reached Certyn.

Mobile and API projects

Step 3 changes with the surface. create_project takes runtimeSurface: web (the default), mobile, or api. Call whoami to see what each one needs.

API. Same as web. Pass a baseUrl, put tokens and keys in environment variables with add_env_var, and describe the endpoints in the wiki.

Mobile. Two calls, because the project and the environment hold different halves. Pass platform (android, ios, windows, or macos) to create_project: it identifies the target and cannot be set anywhere else. Then pass mobileRuntime to update_environment with the Appium server, the device and the build:

{
  "projectIdOrSlug": "acme-app",
  "environmentKey": "production",
  "mobileRuntime": {
    "appiumServerUrl": "https://hub.browserstack.com/wd/hub",
    "appiumUserName": "acme_qa",
    "appiumAccessKey": "your-grid-key",
    "deviceName": "Google Pixel 8",
    "platformVersion": "14.0",
    "app": "bs://<build-hash>"
  }
}

The split lets one app run against several devices or grids: each environment carries its own device and endpoint, while the platform stays on the project. A mobile environment has no baseUrl. The access key is stored as a secret and read back as ********; send that value back to keep it unchanged.

Notes

• Authorization and access remain tenant-scoped and permission-scoped exactly like the Certyn dashboard.
• Run tools return an ID and finish immediately. Nothing blocks while a test executes.
• Anything started over MCP appears in the app's normal run history with the same evidence attached. It is not a side channel.
• Conversation history tools only return tenant-owned conversations.
• For argument details and response payloads, use the MCP Tool Catalog.