Skip to main content

​
Adding a Server​

Use the testpilot mcp add command to register an MCP server for the current Git repository or directory. To add a local server, pass the command that starts the server: 
testpilot mcp add /path/to/mcp-server --flag arg
Testpilot will start the server and connect to it the next time you run testpilot test. To add a remote server, pass the server URL: 
testpilot mcp add https://mcp.example.com
If the server requires authentication, provide credentials as environment variables or HTTP headers with the --env and --header flags. For example, you can pass an environment variable to a local server: 
testpilot mcp add --env API_KEY=SECRET /path/to/mcp-server
Or set an HTTP header for a remote server: 
testpilot mcp add --header 'Authorization: Bearer $MY_TOKEN' https://mcp.example.com
Use single quotes to prevent your shell from expanding environment variables (like $MY_TOKEN above). This prevents secrets from being written to the .testpilot/mcp.json config file. Testpilot expands environment variables from the config file before connecting to a server. See the Environment Variables section for details.

​
Configuration File​

MCP server configurations are stored in a mcp.json file that follows a schema similar to Claude Code and other agents. The file location depends on whether you’re running Testpilot in a Git repository:
  • Git repos: Testpilot searches for .testpilot/mcp.json starting from the current directory up to the repository root. If not found, it creates the file at .testpilot/mcp.json in the repository root.
  • Non-Git directories: Testpilot searches for .testpilot/mcp.json starting from the current directory up through parent directories. If not found, it creates the file at .testpilot/mcp.json in the current directory.
You should commit the .testpilot directory to share MCP server configurations with your team and use them in CI.

​
Local Servers​

Local servers are commands that Testpilot starts as separate processes. Testpilot communicates with these servers through standard input/output. 
{
  "mcpServers": {
    "filesystem-server": {
      "command": "/path/to/mcp-server",
      "args": ["--verbose"],
      "env": {
        "FOO": "bar"
      }
    }
  }
}
If the command field contains no path separators (’/’), Testpilot searches for the command in your $PATH. Otherwise, Testpilot launches the command directly from the specified path.

​
Remote Servers​

Remote servers communicate with Testpilot over HTTPS. 
{
  "mcpServers": {
    "api-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer $API_KEY"
      }
    }
  }
}
Remote servers typically require authentication since they’re accessible over the internet. For non-interactive environments like CI/CD, set credentials in HTTP headers by referencing environment variables in the mcp.json file. The example above sets the Authorization header to the value of the API_KEY environment variable.

​
Environment Variables​

Testpilot expands environment variables in the command, args, env, url, and headers fields before connecting to a server. Use $VAR or ${VAR} to reference environment variables. Environment variables can also have default values with ${VAR:-default_value}, where default_value replaces $VAR when the variable is empty or unset. The example below uses the GH_MCP_SERVER environment variable for the GitHub MCP server URL, with a fallback to the default endpoint: 
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "${GH_MCP_SERVER:-https://api.githubcopilot.com/mcp/}",
      "headers": {
        "Authorization": "Bearer $GH_TOKEN"
      }
    }
  }
}
This configuration uses the default GitHub MCP server while allowing you to override it for specific Testpilot runs. For example, you can restrict GitHub MCP permissions: 
# Restrict GitHub MCP tools to read-only permissions.
GH_MCP_SERVER=https://api.githubcopilot.com/mcp/readonly testpilot test
All environment variables referenced in your MCP configuration must be set when Testpilot starts, unless they include a default value using the ${VAR:-default} syntax. If any required environment variables are missing, Testpilot will fail at startup with an error indicating which variables need to be set. This ensures your MCP servers receive the necessary credentials and configuration before any tests run.