Claude Integration with MCP for Microsoft Graph API

Claude Integration with MCP for Microsoft Graph API

This repository provides a complete solution for integrating Claude with a Model Context Protocol (MCP) server to access Microsoft Graph API.

Step-by-Step Implementation Guide

Phase 1: Setting Up the MCP Server

1. Clone this repository

   git clone https://github.com/JBAgent/Test1.git
   cd Test1
   

2. Install dependencies for the MCP server

   cd mcp-server
   npm install
   

3. Configure environment variables

   cp .env.example .env
   # Edit .env with your Azure AD credentials
   

4. Start the MCP server

   npm start
   

5. Test the MCP server

   # Using the provided test client
   node test-client.js
   
   # Or using curl
   curl -X POST http://localhost:3000/api/graph \
     -H "Content-Type: application/json" \
     -H "X-User-ID: default-user" \
     -d '{"endpoint": "/users", "method": "GET", "queryParams": {"$top": 5}, "allData": false}'
   

Phase 2: Setting Up the Claude Integration

1. Install dependencies for the Claude application

   cd ../claude-app
   npm install
   

2. Configure environment variables

   cp .env.example .env
   # Edit .env with your Anthropic API key and MCP server URL
   

3. Start the Claude application

   npm start
   

4. Test the Claude integration

   curl -X POST http://localhost:4000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"messages": [{"role": "user", "content": "How many users are in our organization?"}]}'
   

Phase 3: Customizing the Integration

1. Add more Graph API functions

   • Edit claude-mcp-integration.js to add specialized functions
   • Update function definitions in claude-app.js

2. Customize the system prompt

   • Edit the system prompt in claude-app.js to tailor Claude's behavior
   • Add domain-specific context for better responses

3. Implement caching (optional)

   • Add Redis for caching common Graph API responses
   • Update the MCP server to check cache before making API calls

4. Add monitoring and logging

   • Implement logging for all Graph API requests
   • Set up monitoring for the MCP server and Claude application

Project Structure

Test1/
├── mcp-server/               # MCP Server for Microsoft Graph API
│   ├── server.js             # Main server implementation
│   ├── test-client.js        # Test client for verification
│   ├── package.json          # Dependencies
│   ├── Dockerfile            # Container configuration
│   └── .env.example          # Example environment variables
│
├── claude-app/               # Claude Application
│   ├── claude-app.js         # Main application server
│   ├── claude-mcp-integration.js  # Integration module
│   ├── package.json          # Dependencies
│   └── .env.example          # Example environment variables
│
└── docs/                     # Documentation
    └── integration-guide.md  # Detailed integration guide

Environment Variables

MCP Server (.env)

AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
PORT=3000
NODE_ENV=development         # Set to 'production' in production

Claude Application (.env)

ANTHROPIC_API_KEY=your-anthropic-api-key
MCP_SERVER_URL=http://localhost:3000
MCP_USER_ID=default-user
PORT=4000

API Endpoints

MCP Server

• POST /api/graph
  • Makes requests to Microsoft Graph API
  • Requires X-User-ID header for authentication
  • Body contains Graph API request options

Claude Application

• POST /api/chat

  • Sends messages to Claude with Graph API capabilities
  • Body contains message array and optional system prompt

• POST /api/analyze-organization

  • Specialized endpoint for organizational analysis
  • Simplifies asking questions about the organization

Graph API Request Options

When making requests to the MCP server, you can include the following options:

{
  "endpoint": "/users",          // Required: Graph API endpoint
  "method": "GET",               // Optional: HTTP method (default: GET)
  "version": "beta",             // Optional: API version (default: beta)
  "queryParams": {},             // Optional: Query parameters
  "body": {},                    // Optional: Request body for POST/PUT/PATCH
  "allData": false               // Optional: Auto-pagination (default: false)
}

Important Note About consistencyLevel

After testing, we've found that the consistencyLevel parameter is generally not supported in many Graph API configurations. We've removed it from all default requests to ensure maximum compatibility.

If you need to use this parameter in your specific environment (for certain advanced directory query scenarios), you can manually add it to the queryParams:

{
  "endpoint": "/users",
  "method": "GET",
  "queryParams": {
    "$top": 5,
    "consistencyLevel": "eventual"
  }
}

However, we recommend testing carefully before using this parameter, as it can cause errors in many environments.

JSON Format Requirements

When making requests to the MCP server, ensure your JSON is properly formatted:

1. Use double quotes for keys and string values:

   {"endpoint": "/users", "method": "GET"}
   

2. Don't nest JSON strings improperly:

   {"queryParams": {"$filter": "displayName eq 'John'"}}
   

3. Use proper JSON types:

   {"allData": true, "count": 10}
   

Getting Microsoft Azure Credentials

To get your AZURE_CLIENT_ID and AZURE_CLIENT_SECRET:

1. Sign in to the Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Create a new registration or use an existing one
4. Copy the Application (client) ID - this is your AZURE_CLIENT_ID
5. Go to Certificates & secrets > New client secret
6. Create a new secret and copy the value - this is your AZURE_CLIENT_SECRET
7. Under API permissions, add Microsoft Graph permissions

Security Considerations

1. Authentication

   • MCP server uses Azure AD authentication for Graph API
   • Claude application should implement proper authentication

2. Authorization

   • MCP server enforces permissions based on user context
   • Implement role-based access control for sensitive operations

3. Data Protection

   • Be mindful of data shared with Claude
   • Implement data retention policies

4. Audit Logging

   • Log all Graph API requests for compliance
   • Monitor for unusual access patterns

Troubleshooting

1. MCP Server Connection Issues

   • Verify Azure AD credentials
   • Check network connectivity
   • Use the provided test-client.js to verify connections

2. JSON Parsing Errors

   • Ensure requests use valid JSON with double quotes
   • Don't send single-quoted strings or improperly escaped characters
   • Check the request format in test-client.js for examples

3. Graph API Errors

   • "Unrecognized query argument: consistencyLevel" - This error indicates that your Graph API configuration doesn't support this parameter. We've removed it from all examples and default behavior.
   • Check permissions in Azure AD - make sure your application has the correct scopes granted
   • Verify request format and parameters
   • Look for rate limiting issues

4. Claude API Errors

   • Validate Anthropic API key
   • Ensure request format is correct

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.