ZERIN
InstallHelpSign in

TROUBLESHOOTING

Common issues and how to fix them.

01

Setup Errors

"command not found: claude"

Claude Code CLI isn't installed or not in your PATH.

Try:

  • Install Claude Code: npm install -g @anthropic-ai/claude-code
  • Or use another MCP client - see the Install page

Config JSON Syntax Error

Your MCP config file has invalid JSON.

Try:

  • Check for missing commas between server entries
  • Ensure all strings use double quotes, not single quotes
  • Validate your JSON at jsonlint.com
  • Copy a fresh config from the Install page

MCP Server Not Starting / "Failed to connect"

Your client can't start or connect to the MCP server.

Try:

  • Verify the URL is exactly https://mcp.zerin.dev/sse
  • Check your internet connection
  • Restart your MCP client completely
  • For Claude Code: run claude mcp list to check config
02

Authentication Issues

"Error: Not authenticated"

Your MCP client isn't connected or the session expired.

Try:

  • Reconnect your MCP client (restart the tool or reconnect)
  • Check your API key is valid on the API Keys page
  • For OAuth: complete the browser authentication flow

OAuth Flow Not Starting

The browser doesn't open for authentication.

Try:

  • Check your MCP client supports OAuth (Claude Code, Cursor, etc.)
  • Use an API key instead - create one on the API Keys page
  • Check your firewall/network isn't blocking the auth redirect

"Unable to get user"

Authentication succeeded but user lookup failed.

Try:

  • Your session may have expired - reconnect your MCP client
  • If using API key, verify it's active on the API Keys page
03

Connection Issues

Can't Connect to MCP Server

Your MCP client can't reach the Zerin server.

Try:

  • Verify the URL is https://mcp.zerin.dev
  • Check your internet connection
  • Make sure your firewall allows HTTPS connections
  • Try the connection in a browser: visit https://mcp.zerin.dev

"Tool not found" or Tools Not Showing

The Zerin tools aren't available in your MCP client.

Try:

  • Restart your MCP client after adding the configuration
  • Check the config JSON syntax is valid
  • Verify the server name is zerin in your config
  • For Claude Code: run claude mcp list to verify
04

Test Your Setup

Use these steps to verify your Zerin setup is working correctly.

Step 1: Check the server is reachable

Open this URL in your browser - you should see a JSON response:

https://mcp.zerin.dev

Step 2: Verify MCP config (Claude Code)

Run this command to check Zerin is configured:

claude mcp list

You should see zerin in the list with status "connected" or "ready".

Step 3: Test the connection

Ask Claude to run the get_started tool:

"Use the Zerin get_started tool"

If it works, you'll see a welcome guide. If not, check the error message against this troubleshooting guide.

Step 4: Create a test todo

Try creating your first todo:

"Create a todo: Test Zerin setup"

Then check your Todos page to see it appear.

05

Common Errors

"Todo not found"

The todo ID doesn't exist or you don't have access.

Try:

  • Use list_todos to see your current todos and their IDs
  • The todo may have been deleted - check with include_completed: true
  • Make sure you're using the correct todo ID (a UUID)

"URL is required for link type notes"

You're adding a link note without a URL.

Try:

  • Include a valid URL when using type: "link"
  • Or use type: "text" for plain text notes

"Cannot set resolution when reopening a todo"

You're trying to reopen a todo while also setting a resolution.

Try:

  • To reopen: use completed: false without resolution
  • Or set resolution: null explicitly
  • Resolution is only for completed todos (done or wont_do)
06

FAQ

How do I see completed todos?

By default, list_todos excludes completed items. Add include_completed: true to see them.

How do I create subtasks?

When creating a todo, set the parent_id to the ID of the parent todo. Use list_todos with parent_id filter to see subtasks.

What's the difference between "done" and "wont_do"?

Both mark a todo as completed, but with different meanings:

  • done - Task was completed successfully
  • wont_do - Task was intentionally skipped or cancelled

Do my todos sync across devices?

Yes! Your todos are stored in the cloud. Use the same account (OAuth or API key) on any device and your todos will be there.

How do I get started?

Call the get_started tool for a quick tutorial with examples. Or visit the Install page for setup instructions.

07

Still Need Help?

If you're still having issues, please open an issue on GitHub with details about your setup and the error you're seeing.