> For the complete documentation index, see [llms.txt](https://help.aikido.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.aikido.dev/ai-and-dev-tools/aikido-mcp/mcp-troubleshooting.md).

# MCP Troubleshooting

When running into issues with the Aikido MCP server, work through the steps below before reaching out to support. If the problem persists, share the output from these steps with the Aikido team.

## Check your Node.js version

The Aikido MCP server requires Node.js 18.19.0 or higher.

Run this in your terminal to verify:

```bash
node -v
```

If your version is below 18.19.0, update Node.js before continuing.

## Run the MCP server directly

Most AI coding tools don't make it easy to get detailed logs for plugin-integrated MCP servers. If the steps above didn't help, try running the MCP server on its own to isolate the issue.

Run the following command in your terminal:

```bash
LOG_LEVEL=debug npx -y @aikidosec/mcp@latest
```

This starts the MCP server outside of any AI tool and triggers the browser login flow if you are not yet authenticated. It outputs debug-level logs directly in your terminal.

If you are using [token authentication](/ai-and-dev-tools/aikido-mcp/token-authentication.md), pass the token directly instead:

```bash
AIKIDO_API_KEY=your_api_key_here LOG_LEVEL=debug npx -y @aikidosec/mcp@latest
```

Look for errors related to authentication, network connectivity, or missing configuration.

## Collect Claude debug logs

If you are using Claude, start it in debug mode:

```bash
claude --debug
```

This writes startup logs (including MCP startup logs) to a file. These logs can contain useful information about connection or configuration problems, but they won't always surface the root cause.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.aikido.dev/ai-and-dev-tools/aikido-mcp/mcp-troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.