MCP Troubleshooting

Connection Issues

"Connection refused" or "SSE connection failed"

Check:

• Your instance URL is correct
• The MCP endpoint is /api/mcp (include the full path)
• Your network can reach the instance (try curl https://livefolio.cloud/api/mcp)

Agent shows no tools available

The MCP handshake didn't complete. Most clients handle this automatically. If using a custom client:

1. Call initialize with protocolVersion: "2024-11-05"
2. Wait for response
3. Call notifications/initialized
4. Then call tools/list

Authentication Errors

"Unauthorized" or 401

1. Verify the API key is valid (not expired or revoked) — check Settings → API Keys
2. Check the Authorization header format: Bearer lf_agent_...
3. If using query parameter: ?key=lf_agent_...
4. Key belongs to the correct workspace

Key was working but stopped

Someone may have revoked it. Generate a new key from Settings → API Keys.

Tool Errors

"Project not found"

• Call list_projects first to get valid project IDs
• IDs are case-sensitive
• Verify the project belongs to your workspace

"Argument is required"

Check the Tools Reference for required parameters.

"Error executing tool"

Check the server logs for details. Common causes:

• Invalid HTML in initial_html or updated_files
• File size exceeding limits
• Database write failure

Debugging

Test with curl

# Initialize
curl -X POST https://livefolio.cloud/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_agent_xxxxxxxxxxxx" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05"},"id":1}'

# List tools
curl -X POST https://livefolio.cloud/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer lf_agent_xxxxxxxxxxxx" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

Inspect Project State

If a tool returns unexpected results, call get_project to inspect the full project state — all files, versions, and comments.

Self-Hosted Troubleshooting

For tunnel issues, database problems, and OSS-specific MCP errors, see Self-Hosting.