AI-Assisted Integration (MCP Server)

Overview

The Guardian MCP Server exposes Guardian’s complete API documentation and OpenAPI specification to AI assistants, enabling intelligent code generation in any programming language. Instead of manually reading documentation and crafting API calls, you can describe what you want to build and let AI generate production-ready integration code.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely access external data sources and tools. Guardian’s MCP server provides:

• Complete API Contracts: All 42+ endpoints with request/response schemas
• Documentation Access: Authentication guides, configuration references, and best practices
• Real-time Updates: Fetches latest specs from GitHub with intelligent caching

Prerequisites

• MCP-compatible AI client (Cursor IDE, Claude Desktop, or similar)

Quick Start: Use Hosted Server (Recommended)

The easiest way to get started is using Guardian’s hosted MCP server. No installation required!

For Cursor IDE

Add to your MCP settings (~/.cursor/mcp.json):

{
  "mcpServers": {
    "guardian-auth": {
      "transport": "sse",
      "url": "https://mcp.guardianhq.io/sse"
    }
  }
}

For Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "guardian-auth": {
      "transport": "sse",
      "url": "https://mcp.guardianhq.io/sse"
    }
  }
}

Verify Connection

After adding the configuration:

1. Restart your AI client
2. Ask the AI: “List all Guardian API endpoints”
3. The AI should use the list_endpoints tool and show 42+ endpoints

---

Available Tools

The MCP server provides three tools that AI assistants can use:

1. list_endpoints

Lists all available Guardian API endpoints organized by category.

Example AI Request:

Show me all available Guardian API endpoints

Output: A categorized list of 42+ endpoints including Passwordless, OAuth, Token management, and more.

2. get_endpoint_details

Retrieves complete API contract for a specific endpoint, including:

• Request body schema with field names, types, and required flags
• Response schemas for all status codes (200, 400, 500)
• Header requirements
• Examples from the OpenAPI spec

Example AI Request:

Get the complete API details for POST /v2/passwordless/init

Output: Full schema with all fields, types, validation rules, and examples.

3. search_docs

Searches Guardian documentation for specific topics.

Example AI Request:

Search documentation for token refresh

Output: Relevant documentation sections with context.

Example Prompts

Passwordless Authentication with SMS/Email OTP

Use this prompt to implement complete passwordless authentication:

I need to implement passwordless authentication using Guardian's OTP flow.
The application should support both SMS and Email as OTP delivery channels.

Requirements:
1. User enters their phone number OR email address
2. System sends OTP to the provided contact
3. User enters the OTP to complete authentication
4. On success, store the access token and refresh token

Please help me:

1. First, use the `get_endpoint_details` tool to fetch the complete API contract for:
   - POST /v2/passwordless/init
   - POST /v2/passwordless/complete

2. Then implement a complete authentication service in Java that:
   - Initiates passwordless flow with proper request body structure
   - Handles OTP resend with the state parameter
   - Completes authentication and extracts tokens
   - Includes proper error handling for 400/500 responses
   - Uses the correct headers (tenant-id)

3. Include example usage showing:
   - SMS OTP flow (channel: "sms", identifier: phone number)
   - Email OTP flow (channel: "email", identifier: email address)

Make sure to use the exact field names and types from the OpenAPI spec.

---

Token Refresh Implementation

Using Guardian MCP, implement automatic token refresh.

1. Get the API details for the refresh token endpoint
2. Create a token manager that:
   - Stores access and refresh tokens
   - Automatically refreshes when access token expires
   - Handles refresh token rotation
3. Implement in TypeScript for a Node.js backend

---

Social Authentication (Google/Facebook)

I want to add Google Sign-In to my React application using Guardian.

1. Use MCP to get the Google authentication endpoint details
2. Show me the complete OAuth flow:
   - Frontend: Get ID token from Google
   - Backend: Exchange with Guardian for access tokens
3. Include error handling for invalid tokens

---

Multi-Language Support

Generate Guardian passwordless authentication clients in:
1. Python (using httpx)
2. Go (using net/http)
3. Rust (using reqwest)

Use the MCP server to get exact API schemas and ensure 
all implementations use identical field names and types.

---

Error Handling

Using Guardian MCP, show me all possible error responses for:
- /v2/passwordless/init
- /v2/passwordless/complete

Create a comprehensive error handler that:
1. Parses Guardian error responses
2. Maps error codes to user-friendly messages
3. Handles retry logic for transient failures

Best Practices

1. Always Request Schema Details First

Before implementing, ask the AI to fetch the complete API contract:

Before writing any code, use get_endpoint_details to fetch 
the complete schema for [endpoint]. Show me all fields, 
types, and required parameters.

2. Specify Your Technology Stack

Be explicit about your programming language and frameworks:

Implement in TypeScript using:
- axios for HTTP calls
- zod for schema validation
- Include proper TypeScript interfaces

3. Request Error Handling

Always include error handling in your prompts:

Include error handling for:
- Network failures
- 400 Bad Request (validation errors)
- 401 Unauthorized
- 500 Internal Server errors

4. Ask for Tests

Request test cases along with implementation:

Also generate unit tests using Jest that:
- Mock API responses
- Test success scenarios
- Test error scenarios
- Validate request payloads

Troubleshooting

1. MCP Server Not Connecting

1. Check Python version: Requires Python 3.11+

   python3 --version

2. Verify dependencies:

   pip install mcp httpx beautifulsoup4 markdownify pyyaml

3. Check path in config: Use absolute paths, not relative

4. View server logs: The MCP server logs to stderr

2. AI Not Using MCP Tools

If the AI isn’t using the Guardian tools, explicitly request them:

Use the Guardian MCP server's get_endpoint_details tool to fetch 
the API schema for /v2/passwordless/init before implementing.

3. Stale Documentation

The MCP server caches documentation for 24 hours. To force refresh:

1. Restart the MCP server
2. Or delete the cache directory: mcp-server/.cache/docs/

Resources

• Guardian GitHub Repository
• MCP Protocol Documentation
• Guardian OpenAPI Spec