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

zoho-mcp-oauth-spike

by johnelamont

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.

Related MCP server: ado-mcp-gateway

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A self-hosted remote MCP server for Azure DevOps that bridges OAuth 2.1 between MCP clients and Microsoft Entra ID, enabling any OAuth-capable client (e.g., Claude Code, Claude Desktop) to access Azure DevOps resources.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      A secure MCP server for CRM operations (contacts and deals) with Auth0 OIDC authentication, role-based access control (sales-rep read-only vs sales-manager full access), and on-behalf-of token exchange.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      A spec-compliant remote MCP server with built-in OAuth 2.1 and Dynamic Client Registration, enabling Notion Custom Agents to connect via 'Sign in with OAuth' without bearer tokens. It supports SSO federation to Google and Microsoft Entra, and includes basic tools like whoami, echo, and slow_task.
      MIT