MCP/Claude Desktop Connector Issue CORS preflight

[jerrice]

Description

In trying to get the MCP API working with Claude Desktop, I cannot get an automatic or manually created connector to connect to the MCP API. Claude Desktop itself gives a generic error, but in testing (with Claude) I found that Homepage's /api/mcp endpoint gives a 401 on OPTIONS requests for CORS preflight, which I would expect to be exempted from auth. This is likely the reason Claude Desktop's connector creation flow is getting tripped up.

homepage version

v2.0.0 (17456f2)

Installation method

Docker

Configuration

Environment: Homepage version v2.0.0 (17456f2) deployed via Docker Compose behind Caddy (however this is reproducible when using CURL against the container's port directly as well.) Claude Desktop for Linux version 1.32885.1 (a757f5).

Related environment settings:
`HOMEPAGE_MCP_ENABLED: "true"`
`HOMEPAGE_MCP_TOKEN: ${HOMEPAGE_MCP_TOKEN}`
`HOMEPAGE_MCP_ALLOW_WRITE: "false"`

Container Logs

No logs from the container or the service itself are relevant, even with LOG_LEVEL: debug.

Browser Logs

No response

Troubleshooting

Reproduce:

1. Enable MCP per the docs
2. Confirm calls work via curl:
   curl -s https://homepage.example.com/api/mcp \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
   Returns 200
3. Test/Attempt OPTIONS request:
   curl -sD - -X OPTIONS https://homepage.example.com/api/mcp \
-H "Origin: https://claude.ai" \
-H "Access-Control-Request-Method: POST" \
-H "Access-Control-Request-Headers: authorization,content-type" \
-o /dev/null
   Returns 401

Expected:
200 or 204 per https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS#preflight_requests_and_credentials

[shamoon]

I think the issue is you're (understandably) trying to use a Claude "connector". Unfortunately that requires oauth and doesnt work with homepage's token auth. I'll update the docs but you can still get this to work as an MCP with claude_desktop_config.json

See https://gethomepage.dev/configs/mcp/#connecting-claude-desktop

[jerrice]

Yes, thank you, the instructions helped tremendously!

[github-actions[bot]]

This discussion has been automatically closed because it was marked as answered. See our contributing guidelines for more details.