zoho-mcp-oauth-spike
by johnelamont
README.md
# zoho-mcp-oauth-spike
A learning spike: a remote **MCP server with its own OAuth authorization server**, running on **Zoho Catalyst AppSail**, that signs users in through **Zoho Accounts** and calls **Zoho CRM v8** on their behalf. Claude.ai connects to it as a custom connector.
**Status: archived (November 2026).** It worked end to end, but it was built to learn, not to run. Don't deploy it as is: there's no security review, no production setup, and sign-in is restricted to one owner account.
## What it does
```
Claude.ai ──OAuth (DCR, PKCE)──▶ this server ──OAuth──▶ Zoho Accounts
│ │
└──── MCP tools (whoami, crm_org) ──┴──▶ Zoho CRM v8, using the server's stored Zoho token
```
This is the same shape Zoho's own MCP service uses ("option B" in `FINDINGS.md`):
- **Its own authorization server**
- Dynamic Client Registration
- its own consent page
- PKCE
- short-lived signed JWT access tokens bound to the `/mcp` resource
- rotating refresh tokens
- **Chained to Zoho sign-in**
- Zoho's consent page and org picker come after ours
- the server keeps one Zoho grant per (Zoho user, CRM org)
- Zoho refresh tokens are encrypted at rest (AES-256-GCM) in the Catalyst Data Store
- **The proxy pattern:** Claude.ai never sees a Zoho token. Our token carries an `org` claim, and the server uses the matching stored Zoho grant.
- **Failure paths:** a revoked Zoho link is marked dead, and the user is told to reconnect. Token, code and secret values never appear in logs.
## Zoho behaviour we found that the docs don't spell out
Observed against real Zoho Accounts (US) and CRM v8, November 2026:
1. **Requesting only `openid` returns no ID token.** Zoho's userinfo endpoint still works with that token, and returns only `aud`, `azp`, `exp`, `iat`, `iss` and `sub`.
2. **`sub` is `<ZUID>.<number>`.** The number **changes when the user removes the app and authorizes it again**, and stays the same across re-consents in between. Use the ZUID (the part before the dot) as the stable identity, not the whole `sub`.
3. **Token endpoint errors come back as HTTP 200** with an `error` field in the body.
4. **Removing the app** under the user's Zoho Accounts connected apps **cancels outstanding access tokens immediately**.
5. **The revoke endpoint answers HTTP 400 for a token that's already dead.**
6. **A sandbox org's API calls go through the main host**, `www.zohoapis.com`, with an org-bound token.
7. **Claude.ai allows one custom connector per URL**, so one user can't connect two orgs side by side through the same URL.
## Files
| File | What |
|---|---|
| `server.py` | Configuration, MCP server, tools, routes |
| `auth_server.py` | The OAuth authorization server: registration, consent, tokens, Zoho callback |
| `zoho.py` | Zoho Accounts and CRM client: token exchange, refresh, revoke, userinfo, org lookup, encryption |
| `storage.py` | In-memory and Catalyst Data Store storage |
| `tests/test_zoho_signin.py` | 81 checks against a fake Zoho (token, userinfo, JWKS, revoke, CRM org): refusals, refresh, dead links, ZUID identity, log hygiene. Run it with `python tests/test_zoho_signin.py`. |
| `build.ps1`, `run-local.ps1` | Build for AppSail (Linux wheels); run locally against real Zoho |
| `app-config.example.json` | AppSail config template. The real `app-config.json` is never committed. |
| `BRIEF*.md`, `FINDINGS.md`, `STAGE2.md` | Stage briefs, research findings, and the full build and test log, with every decision and dead end |
Identifiers in the docs (Zoho user and org IDs, URLs) are replaced with placeholders.
## Built with
Python 3.12, the MCP Python SDK, Starlette and uvicorn, PyJWT, cryptography, and the Zoho Catalyst SDK. Built with Claude Code as a pair, under a written set of governance rules (approval gates, audit logging, failure paths).
## License
MIT. See `LICENSE`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues