Connecting to Claude Code

Claude Code integrates with Maeris through the Model Context Protocol. Once connected, every Maeris tool — test generation, API scanning, security scanning, flow management — is available directly from Claude Code's chat interface in natural language.

How Claude Code Uses .mcp.json

Claude Code reads the .mcp.json file in your project root at startup. This file tells Claude Code which MCP servers to launch and how to communicate with them. The Maeris entry instructs Claude Code to run maeris serve, which starts the Maeris MCP server in stdio mode.

Claude Code communicates with the MCP server over stdio (standard input/output) — no separate port or network connection is needed. The server process is automatically started and stopped by Claude Code.

The .mcp.json Format

A standard Maeris .mcp.json file looks like this:

{
  "mcpServers": {
    "maeris": {
      "command": "maeris",
      "args": ["serve"]
    }
  }
}

This file is created automatically by maeris app init. You should not need to edit it manually unless you have a non-standard Python environment. If maeris is not on your PATH, specify the full path:

{
  "mcpServers": {
    "maeris": {
      "command": "/usr/local/bin/maeris",
      "args": ["serve"]
    }
  }
}

Restart your editor after init

Claude Code reads .mcp.json only at startup. After running maeris app init or modifying .mcp.json, restart Claude Code completely for the Maeris tools to become available.

The maeris serve Command

maeris serve starts the Maeris MCP server in stdio mode. You do not need to run this manually — Claude Code launches it automatically. However, you can run it directly to test connectivity:

maeris serve

When run manually, the server prints its registered tools to stderr and then waits for MCP protocol messages on stdin. Press Ctrl+C to stop it.

Invoking MCP Tools Through Claude Code

Once connected, you can invoke any Maeris tool by describing your intent to Claude Code in natural language. Claude Code handles the tool selection and parameter filling automatically:

Example prompts and their tool calls

"Scan my project for APIs" → calls api_scan
"Generate tests for my login page" → calls generate_tests
"Run a security scan" → calls security_scan
"Create an environment called staging" → calls add_environment
"Show me all my collections" → calls list_collections
"Run all my tests and fix failures" → calls run_and_fix_tests

Verifying Connection with maeris_status

To verify that Claude Code is successfully connected to Maeris and that you are authenticated, ask Claude Code to call the maeris_status tool:

Prompt to Claude Code: "Check my Maeris status" or "Call maeris_status"

A successful response looks like:

{
  "authenticated": true,
  "user": "alex@example.com",
  "application": "my-web-app",
  "server": "api.maeris.io",
  "status": "connected"
}

Troubleshooting

Tools not appearing in Claude Code

Fix: Ensure .mcp.json exists in your project root and restart Claude Code. Verify the file is valid JSON with cat .mcp.json | python3 -m json.tool.

"maeris: command not found" in MCP logs

Fix: Claude Code launches maeris serve using the same PATH as your login shell. If maeris is installed in a non-standard location, specify the full absolute path in .mcp.json as the command value. Find the path with which maeris.

Authentication errors from Claude Code

Fix: Run maeris auth login in your terminal to refresh your token, then restart Claude Code. See the Authentication & Login guide.

General diagnostics

maeris doctor

The doctor command checks all aspects of your setup and pinpoints any issues. See the Diagnosing Setup Issues guide.

Next Steps

For a complete list of all tools available through Claude Code, see the Available MCP Tools Overview.