Health Checks

Verify your MCP server setup is working correctly.

After installing the MCP server and configuring your IDE, run through this checklist to confirm everything is working end-to-end.

Verification checklist

Work through each item in order. If any step fails, check the common failures section below.

• MCP API key created in Project Settings > MCP
• npm run build completes without errors in packages/mcp-server/
• IDE shows the MCP server in its connected tools list
• list_projects returns at least one project
• get_project_context returns project data for your default project
• list_recommendations returns recommendation data

Testing from the command line

You can also verify the server starts correctly outside of your IDE by running it directly:

INDEXMIND_API_KEY=imcp_YOUR_KEY \
  node packages/mcp-server/dist/index.js \
  --api-url https://api.indexmind.ai \
  --log-level debug

If the server starts without errors and logs a "ready" message at the debug level, the build and configuration are valid. The server will wait for an MCP client (your IDE) to connect via stdio.

Common failures

"Server not found" or "Could not start MCP server"

Cause: The IDE cannot locate the server entry point.

Fix: Double-check the absolute path in your IDE's MCP configuration. The path must point to the compiled dist/index.js file, not the TypeScript source.

# Verify the file exists
ls -la /path/to/packages/mcp-server/dist/index.js

"MODULE_NOT_FOUND" or missing dependency errors

Cause: Dependencies are not installed or the build is stale.

Fix: Re-install and rebuild:

cd packages/mcp-server
npm install
npm run build

"Unauthorized" or "Invalid API key"

Cause: The API key is missing, expired, or does not have the correct scope.

Fix:

1. Confirm the INDEXMIND_API_KEY environment variable is set in your IDE's MCP configuration.
2. Verify the key starts with imcp_ and was created in Project Settings > MCP.
3. Ensure your account is on the Starter plan or above. Free plans do not include MCP access.

"No projects returned" from list_projects

Cause: The API key is not org-scoped, or the organization has no projects.

Fix: MCP API keys must be org-scoped to access projects. Create a new key in Project Settings > MCP and confirm it is associated with your organization, not a personal scope.

"Connection timeout" or "ECONNREFUSED"

Cause: The MCP server cannot reach the IndexMind API.

Fix:

1. Check the value of INDEXMIND_API_URL (or --api-url). For production, use https://api.indexmind.ai.
2. If you are running the backend locally, ensure it is started and listening on the expected port (default http://localhost:8080).
3. Check for firewall rules or VPN configurations that may block outbound connections.

Write tools not appearing

Cause: The server was started with the --readonly flag.

Fix: Remove --readonly from the args array in your IDE's MCP configuration if you need write access. See the Tools Reference for details on which tools require write access.