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

bashCOPY
npm 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.

bashCOPY
npm run inspect

This opens the Inspector at http://localhost:6274.

Connect to your server

1. Set Transport Type to Streamable HTTP
2. Set URL to http://localhost:3000/mcp
3. Open Authentication → add a header:
   • Name: x-mcp-secret
   • Value: the MCP_SECRET value from your .env file
4. Click Connect

You should see a green ● Connected status and your tools listed in the left panel.

Run a tool

1. Click on a tool name (e.g., echo or get_data)
2. Fill in the required parameters
3. Click Run Tool
4. 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:

bashCOPY
npm 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:

bashCOPY
curl 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

The .env file is auto-generated during agenticmarket create with a random MCP_SECRET. Never commit it to version control.

---

Next steps

• Add more tools to your server
• Run the pre-publish audit
• Publish on AgenticMarket
• Full tutorial: How to Create an MCP Server
• Deep dive: How to Test MCP Servers (blog)