AgenticMarketTesting MCP Servers Locally
Every server scaffolded with agenticmarket create includes built-in testing tools. This guide covers how to run your server locally, test with the MCP Inspector, and debug common issues. For a full build-to-deploy walkthrough, see How to Create an MCP Server.
Start the dev server
bashnpm run dev
Your server starts at http://localhost:3000 with hot-reload enabled. Every file change restarts the server automatically.
The dev logger prints color-coded request logs with millisecond timestamps:
[14:32:01.123] ← POST /mcp 200 12ms # green = success
[14:32:02.456] ← GET /health 200 1ms # green
[14:32:05.789] ← POST /mcp 401 0ms # yellow = client error
[14:32:10.012] ← POST /mcp 500 3ms # red = server error
The logger is automatically disabled when NODE_ENV=production.
MCP Inspector (visual UI)
The MCP Inspector is a browser-based tool that lets you connect to your server, list tools, and call them interactively.
bashnpm run inspect
This opens the Inspector at http://localhost:6274.
Connect to your server
- Set Transport Type to
Streamable HTTP - Set URL to
http://localhost:3000/mcp - Open Authentication → add a header:
- Name:
x-mcp-secret - Value: the
MCP_SECRETvalue from your.envfile
- Name:
- Click Connect
You should see a green ● Connected status and your tools listed in the left panel.
Run a tool
- Click on a tool name (e.g.,
echoorget_data) - Fill in the required parameters
- Click Run Tool
- The response appears in the right panel
Ping
Click the Ping tab and send a ping. A successful response is an empty {} — this is correct per the MCP specification.
CLI mode (CI-ready)
For automated testing in CI/CD pipelines:
bashnpm run test:tools
This runs the Inspector in headless CLI mode, connects to your server, lists tools, and exits. Non-zero exit code on failure.
Health endpoint
Every server includes a /health endpoint that bypasses authentication:
bashcurl http://localhost:3000/health
Returns 200 OK with the server status. Use this for uptime monitoring and load balancer health checks.
Troubleshooting
"Unauthorized" on every request
Your x-mcp-secret header does not match the MCP_SECRET in your .env file. Copy the exact value — no extra spaces.
"Server not initialized"
The MCP handshake failed. This usually means:
- The Inspector lost its session. Click Reconnect.
- Your server restarted (hot-reload) while the Inspector was connected. Click Reconnect.
OPTIONS requests returning 401
CORS preflight requests (OPTIONS) do not carry custom headers. The security middleware skips authentication for OPTIONS requests automatically. If you see 401 on OPTIONS, update your security.ts middleware.
Empty response on Ping
This is correct. The MCP spec defines ping as returning {}.
Environment files
| File | Purpose | Committed to git? |
|---|---|---|
.env | Your real secrets and config. The server reads this. | No (gitignored) |
.env.example | Template showing required variables. For other developers. | Yes |
The .env file is auto-generated during agenticmarket create with a random MCP_SECRET. Never commit it to version control.