Update README with concise setup instructions and usage guide#70
Update README with concise setup instructions and usage guide#70kashvipahuja-dev wants to merge 1 commit intodescope:mainfrom
Conversation
kashvipahuja-dev
requested review from
anvibanga,
gaokevin1 and
mrunankpawar
as code owners
👷 Deploy request for express-mcp-server pending review.Visit the deploys page to approve it
|
👷 Deploy request for mcp-example-oauth pending review.Visit the deploys page to approve it
|
|
@kashvipahuja-dev is attempting to deploy a commit to the descope Team on Vercel. A member of the Team first needs to authorize it. |
There was a problem hiding this comment.
Pull request overview
Updates the example agent README to provide clearer setup instructions and a usage guide for the Claude + MCP + Descope + Gmail integration.
Changes:
- Expanded README with feature list, prerequisites, quick start steps, and usage examples.
- Added architecture/security explanations and project structure overview.
- Added “Learn more” links and a license section.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ## License | ||
|
|
||
| MIT |
There was a problem hiding this comment.
README lists the project license as MIT, but package.json in this example declares ISC. Please align the README License section with the actual licensing for this package (or update package.json if MIT is intended).
| # Claude MCP Gmail Agent with Human-in-the-Loop Approval | ||
|
|
||
| A secure AI agent that integrates Gmail using Claude's Agents SDK, Model Context Protocol (MCP), and Descope for authentication, authorization, and progressive OAuth scoping with human approval for sensitive actions. |
There was a problem hiding this comment.
The intro says this agent integrates Gmail using “Claude's Agents SDK”, but the implementation under src/ appears to use @anthropic-ai/sdk directly and does not import or reference @anthropic-ai/claude-agent-sdk. Please update the README to match the actual SDK used, or update the code to use the Agents SDK if that’s the intent.
| - 🎫 Human-in-the-loop approval via Descope Enchanted Links | ||
| - 🔒 Agent never directly handles Gmail tokens (Agent → MCP → Descope → Gmail) | ||
|
|
There was a problem hiding this comment.
The README claims the agent “never directly handles Gmail tokens”, but src/cli-agent.ts fetches a Gmail access token from Descope (/v1/mgmt/outbound/app/user/token/latest) and uses it to call the Gmail API directly when sending an approved email. This is a security/architecture mismatch; please adjust the README description (and the Architecture/Security sections) to reflect the real token flow.
| ``` | ||
| User → Agent (Claude) → MCP Server → Descope → Gmail API | ||
| ``` | ||
|
|
||
| The agent never directly handles Gmail OAuth tokens. The MCP server requests them from Descope, creating an extra security boundary. |
There was a problem hiding this comment.
The architecture diagram shows “User → Agent → MCP Server → Descope → Gmail API”, but the current implementation also calls Descope/Gmail directly from the agent process (e.g., approval route in src/cli-agent.ts). Please update the diagram/description to match the actual call paths so readers don’t assume all Gmail calls are isolated behind the MCP server.
| Create a `.env` file: | ||
|
|
||
| ```env | ||
| ANTHROPIC_API_KEY=your_anthropic_api_key_here | ||
| DESCOPE_PROJECT_ID=your_descope_project_id_here | ||
| DESCOPE_CLIENT_ID=your_descope_client_id_here | ||
| DESCOPE_CLIENT_SECRET=your_descope_client_secret_here | ||
| MCP_SERVER_ID=your_mcp_server_id_here | ||
| ``` |
There was a problem hiding this comment.
The .env variables listed here don’t match the checked-in .env.example (which currently omits DESCOPE_CLIENT_ID). Since src/auth.ts requires DESCOPE_CLIENT_ID, consider either updating the README to reference .env.example or ensuring the documented env vars stay in sync with it to prevent setup confusion.
1 participant
Claude Agent README.md