Mcp

Troubleshooting

Common issues, debugging tips, and MCP Inspector usage for the maps.guru MCP server.

Common issues

"No authentication provided" error

What you see: The server starts but tool calls fail with an auth error pointing you at auth login.

Fix: Pick one path.

Recommended — sign in once with the CLI:

npx @invarya/maps-mcp auth login
npx @invarya/maps-mcp auth status   # confirm it worked

The server reads JWT credentials from your OS keychain on every launch. No config-file env vars needed.

Or — paste a mapx_ key into your client config:

Confirm MAPS_GURU_API_KEY is set in your client's config
The key should start with mapx_
Check it's active at maps.guru/dashboard/tokens and hasn't been revoked

{
  "env": {
    "MAPS_GURU_API_KEY": "mapx_your_full_key_here"
  }
}

Authentication priority: MAPS_GURU_BEARER_TOKEN env > keychain JWT (from auth login) > MAPS_GURU_API_KEY env.

Server won't start

What you see: Your MCP client shows "maps-guru" as disconnected or unresponsive.

Fix:

Check Node.js 18+ is installed: node --version

Run the server directly and watch for errors:

MAPS_GURU_API_KEY=mapx_your_key npx @invarya/maps-mcp

Clear the npx cache if you're on a flaky install: npx clear-npx-cache

"Quota exceeded" error

What you see: Tools return 403s mentioning quota.

Fix:

Ask the assistant: "How many API calls have I used this month?"
Upgrade at maps.guru/dashboard/billing
Or wait for the monthly reset (1st of each month, UTC)

No tools showing up

What you see: Your AI assistant doesn't list any maps.guru tools.

Fix:

Restart the client after any config change — most clients only read the config at startup
Check the JSON is valid (no trailing commas, properly quoted keys)
Confirm the config file path is right for your OS
Make sure npx is on your PATH

Debugging with MCP Inspector

The MCP Inspector is the official way to poke at an MCP server directly.

Launch it

MAPS_GURU_API_KEY=mapx_your_key npx @modelcontextprotocol/inspector npx @invarya/maps-mcp

The web UI lets you list tools and resources, invoke them with custom parameters, and watch the raw MCP protocol messages (including error responses).

Quick sanity check

Tools tab — all 15 tools should be listed with descriptions
Resources tab — mapsguru://presets and mapsguru://info should both appear
Pick a tool — call geocode with { "query": "Paris" } to confirm end-to-end connectivity

Error reference

Error	Cause	Fix
`No authentication provided`	No keychain JWT and no env var set	Run `auth login` or set `MAPS_GURU_API_KEY`
`Access token expired`	Keychain JWT expired, no refresh	Run `auth login` again
`MAPS_GURU_API_KEY is required`	Env variable not set	Add the key to your client config or `auth login`
`Invalid API key`	Key doesn't exist or was revoked	Check the dashboard
`API key quota exceeded`	Monthly limit hit	Upgrade your plan or wait for reset
`Rate limited`	Too many requests per second	Slow down or add small delays between calls
`Network error`	Can't reach maps.guru API	Check your connection
`Style not found`	Unknown style slug or ID	Use `list_styles` to find valid identifiers
`Dataset not found`	Unknown dataset ID	Use `list_datasets` to find valid IDs

Logging

stdout is reserved for MCP protocol messages, so the server writes all logs to stderr. To capture them:

MAPS_GURU_API_KEY=mapx_key npx @invarya/maps-mcp 2>mcp-debug.log
cat mcp-debug.log

Getting help

GitHub Issues — report bugs at the maps.guru repository
Discord — join the community for real-time help
Email — hello@invarya.com

Examples

Real-world usage scenarios for the maps.guru MCP server with step-by-step walkthroughs.