Skip to main content
Glama
zoho-mcp-oauth-spike

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`.