Runs Proctor exams against MCP servers, streams results, and manages Fly.io machines used for exam execution.
Also known as pulsemcp/mcp-servers, proctor-mcp-server
- Stars
- 81
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 0.1.9
- Last commit
- Oct 9, 2026
- License
- MIT
What is Proctor MCP?
Proctor runs Proctor exams against MCP servers, streams results, and manages Fly.io machines used for exam execution. It exposes 4 tools, such as exams, exams_readonly, machines.
Summary generated from the project's README
About Proctor MCP server
Testing MCP servers for protocol compliance and functionality is what proctor enables for the PulseMCP team. This internal tool allows developers to execute specific exams, manage the underlying infrastructure, and monitor real-time execution logs through NDJSON streaming. It connects directly to the PulseMCP Proctor API to handle exam logic and result tracking.
Users interact with the server via an MCP client like Claude Desktop using a required PROCTOR_API_KEY. The server provides granular control through tool groups, allowing you to enable full access or read-only modes for both exams and machine management. For example, you can use the exams group to run tests or the machines group to oversee Fly.io instances.
Beyond just running tests, the server manages the lifecycle of the hardware used for these tasks. You can list active Fly.io machines with get_machines, stop problematic tests using cancel_exam, or perform cleanup by calling destroy_machine. This makes it a comprehensive environment for regression testing and infrastructure oversight.
What you can do with it
- 1Monitor exam infrastructureCheck which Fly.io machines are currently active and being used for running tests.
- 2Clean up cloud resourcesDelete Fly.io machines that were created during the exam process once testing is complete.
Written from the project's README. Every use case is checked against a quote from it.
How to install Proctor MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Proctor MCP in Claude Code
$ claude mcp add --env 'PROCTOR_API_KEY=<YOUR_PROCTOR_API_KEY>' proctor -- npx -y proctor-mcp-serverInstall Proctor MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"proctor": {
"command": "npx",
"args": [
"-y",
"proctor-mcp-server"
],
"env": {
"PROCTOR_API_KEY": "<YOUR_PROCTOR_API_KEY>"
}
}
}
}Install Proctor MCP in VS Code
.vscode/mcp.json
{
"servers": {
"proctor": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"proctor-mcp-server"
],
"env": {
"PROCTOR_API_KEY": "<YOUR_PROCTOR_API_KEY>"
}
}
}
}Install Proctor MCP in VS Code CLI
$ code --add-mcp '{"name":"proctor","type":"stdio","command":"npx","args":["-y","proctor-mcp-server"],"env":{"PROCTOR_API_KEY":"<YOUR_PROCTOR_API_KEY>"}}'Install Proctor MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"proctor": {
"command": "npx",
"args": [
"-y",
"proctor-mcp-server"
],
"env": {
"PROCTOR_API_KEY": "<YOUR_PROCTOR_API_KEY>"
}
}
}
}Install Proctor MCP in Codex
$ codex mcp add proctor --env 'PROCTOR_API_KEY=<YOUR_PROCTOR_API_KEY>' -- npx -y proctor-mcp-serverInstall Proctor MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.proctor] command = "npx" args = ["-y", "proctor-mcp-server"] [mcp_servers.proctor.env] PROCTOR_API_KEY = "<YOUR_PROCTOR_API_KEY>"
Install Proctor MCP in Gemini CLI
$ gemini mcp add -s user -e 'PROCTOR_API_KEY=<YOUR_PROCTOR_API_KEY>' proctor npx -- -y proctor-mcp-serverInstall Proctor MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"proctor": {
"command": "npx",
"args": [
"-y",
"proctor-mcp-server"
],
"env": {
"PROCTOR_API_KEY": "<YOUR_PROCTOR_API_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Proctor MCP tools 4
Detected from the READMEexamsexams_readonlymachinesmachines_readonly
Configuration
PROCTOR_API_KEYRequiredSecretAPI key for PulseMCP Proctor API authentication.
PROCTOR_API_URLBase URL for Proctor API.
TOOL_GROUPSComma-separated list of enabled tool groups.
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubProctor MCP Server
Haven't heard about MCP yet? The easiest way to keep up-to-date is to read our weekly newsletter at PulseMCP.
This is an MCP (Model Context Protocol) Server for running Proctor exams against MCP servers. It provides tools for executing tests, managing exam infrastructure, and tracking test results through direct integration with the PulseMCP Proctor API.
Note: This is an internal tool for the PulseMCP team. The source code is public for reference purposes, but the server requires API keys that are not publicly available.
Table of Contents
Highlights
Exam Execution: Run Proctor exams against MCP servers to test functionality and protocol compliance.
Result Management: Save and retrieve exam results for comparison and regression testing.
Infrastructure Control: List, manage, and clean up Fly.io machines used for exam execution.
Tool Groups: Enable/disable tool groups via TOOL_GROUPS environment variable. Each group has a base variant (full access) and a _readonly variant (read-only access).
Streaming Results: Real-time exam execution logs with NDJSON streaming.
Capabilities
This server is built and tested on macOS with Claude Desktop. It should work with other MCP clients as well.
| Tool Name | Tool Group | Read/Write | Description |
|---|---|---|---|
get_proctor_metadata |
exams | read | Get available runtimes and exams for Proctor testing. |
run_exam |
exams | write | Execute a Proctor exam against an MCP server. |
get_machines |
machines | read | List active Fly.io machines used for Proctor exams. |
destroy_machine |
machines | write | Delete a Fly.io machine. |
cancel_exam |
machines | write | Cancel a running Proctor exam. |
Tool Groups
This server organizes tools into groups that can be selectively enabled or disabled. Each group has two variants:
- Base group (e.g.,
exams): Full read + write access - Readonly group (e.g.,
exams_readonly): Read-only access
Available Groups
| Group | Tools | Description |
|---|---|---|
exams |
2 | Full exam execution (read + write) |
exams_readonly |
1 | Exam metadata (read only) |
machines |
3 | Full machine management (read + write) |
machines_readonly |
1 | Machine listing (read only) |
Tools by Group
- exams / exams_readonly:
- Read-only:
get_proctor_metadata - Write:
run_exam
- Read-only:
- machines / machines_readonly:
- Read-only:
get_machines - Write:
destroy_machine,cancel_exam
- Read-only:
Environment Variables
| Variable | Description | Default |
|---|---|---|
PROCTOR_API_KEY |
API key for PulseMCP Proctor API (required) | - |
PROCTOR_API_URL |
Base URL for Proctor API | https://admin.pulsemcp.com |
TOOL_GROUPS |
Comma-separated list of enabled tool groups | exams,machines (all groups) |
Examples
Enable all tools with full access (default):
# No TOOL_GROUPS needed - all base groups enabled
Enable only exam tools:
TOOL_GROUPS=exams
Enable machines with read-only access:
TOOL_GROUPS=machines_readonly
Enable all groups with read-only access:
TOOL_GROUPS=exams_readonly,machines_readonly
Mix full and read-only access per group:
# Full exam access, read-only machines
TOOL_GROUPS=exams,machines_readonly
Usage Tips
- Use
get_proctor_metadatato discover available runtimes and exam types - Run exams with
run_examto test MCP servers with streaming progress logs - Use
get_machinesto monitor active exam infrastructure - Clean up machines with
destroy_machinewhen no longer needed - Use
cancel_examto stop a stuck or slow exam before destroying the machine
Examples
Get Available Exams
User: What exams can I run with Proctor?
Assistant: I'll check what exams are available.
[Calls get_proctor_metadata]
Here are the available exams:
**Runtimes:**
- Proctor v0.0.37 (id: v0.0.37)
**Exams:**
- Auth Check (id: proctor-mcp-client-auth-check) - Verifies authentication mechanisms
- Init Tools List (id: proctor-mcp-client-init-tools-list) - Tests initialization and tool listing
Monitor Infrastructure
User: What machines are currently running?
Assistant: I'll check the active Fly machines.
[Calls get_machines]
There are 2 active machines:
1. **machine-abc123** - Running in sjc region (created 10 minutes ago)
2. **machine-def456** - Stopped in iad region (created 1 hour ago)
Setup
Claude Desktop
Make sure you have your Proctor API key ready.
Then proceed to the setup instructions below. If this is your first time using MCP Servers, you'll want to make sure you have the Claude Desktop application and follow the official MCP setup instructions.
Manual Setup
You're going to need Node working on your machine so you can run npx commands in your terminal. If you don't have Node, you can install it from nodejs.org.
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Modify your claude_desktop_config.json file to add the following:
{
"mcpServers": {
"proctor": {
"command": "npx",
"args": ["-y", "proctor-mcp-server"],
"env": {
"PROCTOR_API_KEY": "your-api-key-here",
"TOOL_GROUPS": "exams,machines"
}
}
}
}
Restart Claude Desktop and you should be ready to go!
For read-only access:
{
"mcpServers": {
"proctor-readonly": {
"command": "npx",
"args": ["-y", "proctor-mcp-server"],
"env": {
"PROCTOR_API_KEY": "your-api-key-here",
"TOOL_GROUPS": "exams_readonly,machines_readonly"
}
}
}
}
Development
Quick Setup
# Install dependencies
npm run install-all
# Build the server
npm run build
# Set your API key
export PROCTOR_API_KEY="your-api-key-here"
# Run the server
cd local && npm start
License
MIT
Proctor MCP questions
How do I add Proctor MCP to Claude Code?
Run claude mcp add --env 'PROCTOR_API_KEY=<YOUR_PROCTOR_API_KEY>' proctor -- npx -y proctor-mcp-server in your terminal. Add --scope user to make it available in every project.
How do I add Proctor MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Proctor MCP provide?
It exposes 4 tools, including exams, exams_readonly, machines, machines_readonly.
How do I authenticate the Proctor MCP server?
You provide a Proctor API key via the PROCTOR_API_KEY environment variable, which is required and not publicly available.
What tools can run exams against an MCP server?
The exams tool group provides get_proctor_metadata to list runtimes and exams and run_exam to execute an exam with streaming logs.
Can I limit the server to read-only tools?
Yes, each tool group has a readonly variant such as exams_readonly or machines_readonly, set through TOOL_GROUPS.
How do I clean up exam infrastructure?
Use get_machines to list active Fly.io machines, cancel_exam to stop a running exam, and destroy_machine to delete a machine.
What environment variable controls which tools are enabled?
TOOL_GROUPS takes a comma-separated list of tool groups and defaults to exams,machines (all groups).