Auth-mcp by danielsantoslgo - MCP Server

Auth0 AI MCP Server

This project sets up an Auth0 AI MCP (Model Context Protocol) Server that enables the creation of AI-powered tools integrated with various third-party services via Auth0 for secure authorization. It leverages Vercel AI, Vercel AI SDK, and Next.js Auth0 to provide a robust framework for developing intelligent applications that can interact with external APIs.

Features

Auth0 Integration: Securely obtain access tokens for various OAuth connections (e.g., Google Calendar, Slack, GitHub) using Auth0.
AI Tooling: Define and execute AI tools that perform specific actions by utilizing acquired access tokens.
Error Handling: Gracefully manage authorization errors using FederatedConnectionError.
Extensible: Easily add new tools and integrations by defining new authorization configurations and tool implementations.
Standard I/O Transport: The server communicates over standard input/output (stdio), making it suitable for various deployment environments.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

Node.js (LTS recommended)
npm or Yarn
Auth0 account and configured applications
Vercel account (for deployment)

Installation

Clone the repository:

git clone <your-repository-url>
cd <your-repository-name>

Install dependencies:
```
npm install
# or
yarn install
```

Running the Server

To run the MCP server, execute the main script:

node <path-to-your-server-file>.js

For the provided code, if saved as server.js, you would run:

node server.js

The server will log Auth0 AI MCP Server running on stdio to stderr.

Core Concepts

The server operates on the Model Context Protocol, allowing an AI model to interact with external tools.

Auth0 AI Configuration

The Auth0AI class from @auth0/ai-vercel is used to configure authorization for different third-party services. The withTokenForConnection method facilitates obtaining access tokens using refresh tokens from the user's session.

File Path Example: src/lib/auth0-ai/withGoogleCalendar.ts (or similar, based on your project structure)

import { auth0 } from "@/lib/auth0";
import { Auth0AI } from "@auth0/ai-vercel";

const auth0AI = new Auth0AI();

export const withGoogleCalendar = auth0AI.withTokenForConnection({
  refreshToken: async () => {
    const session = await auth0.getSession();
    const refreshToken = session?.tokenSet.refreshToken as string;
    return refreshToken;
  },
  connection: "google-oauth2",
  scopes: ["https://www.googleapis.com/auth/calendar.freebusy"],
});

Tool Creation

Tools are defined using the tool function from the Vercel AI SDK. These tools encapsulate the logic for interacting with third-party APIs, using the access tokens provided by Auth0 AI. Error handling, specifically for authorization issues, is crucial.

File Path Example: src/tools/checkUsersCalendar.ts (or similar)

import { tool } from "ai";
import { addHours, formatISO } from "date-fns";
import { GaxiosError } from "gaxios";
import { google } from "googleapis";
import { z } from "zod";
import { withGoogleCalendar } from "@/lib/auth0-ai/withGoogleCalendar";
import { getAccessTokenForConnection } from "@auth0/ai-vercel";
import { FederatedConnectionError } from "@auth0/ai/interrupts";

export const checkUsersCalendar = withGoogleCalendar(
  tool({
    description: "Check user availability on a given date on their calendar",
    parameters: z.object({
      date: z.coerce.date(),
    }),
    execute: async ({ date }) => {
      const accessToken = getAccessTokenForConnection();
      try {
        const calendar = google.calendar("v3");
        const auth = new google.auth.OAuth2();
        auth.setCredentials({ access_token: accessToken });

        const response = await calendar.freebusy.query({
          auth,
          requestBody: {
            timeMin: formatISO(date),
            timeMax: addHours(date, 1).toISOString(),
            timeZone: "UTC",
            items: [{ id: "primary" }],
          },
        });
        return {
          available: response.data?.calendars?.primary?.busy?.length === 0,
        };
      } catch (error) {
        if (error instanceof GaxiosError && error.status === 401) {
          throw new FederatedConnectionError(
            "Authorization required to access the Federated Connection"
          );
        }
        throw error;
      }
    },
  })
);

Extending Functionality

Adding New Auth0 Connections

To integrate with a new service via Auth0:

Define a new authorization configuration similar to withGoogleCalendar or withSlack. Specify the connection name (from your Auth0 setup) and the required scopes.
- Note on Connections: Auth0 supports a wide range of connections/strategies (e.g., google-oauth2, sign-in-with-slack, github, facebook, twitter, office365, etc.). If a specific strategy isn't directly listed or is custom, Auth0 will default to the oauth2 strategy. In such cases, you can use a descriptive name for the connection but clarify that it uses the oauth2 strategy.
Save this configuration in an appropriate file path, for example, src/lib/auth0-ai/withYourNewService.ts.

Creating New Tools

Once an authorization configuration is in place, you can create new tools:

Import the relevant with... function (e.g., withSlack).
Use tool to define your new tool, providing a description, parameters (using zod for validation), and an execute function.
Within the execute function, retrieve the access token using getAccessTokenForConnection() and use it to interact with the third-party API.
Implement robust error handling, especially for FederatedConnectionError for authorization issues.
Save the tool implementation in a logical file path, for example, src/tools/yourNewTool.ts.

Updating Vercel AI Tools

After creating new authorization configurations and tools, ensure they are integrated into your Vercel AI application. This typically involves updating the Vercel AI configuration to recognize and utilize these new tools, making them accessible to your AI models.

Notes

TypeScript: Leverage TypeScript for strong typing to ensure type safety for parameters and return values.
Error Handling: Always handle potential errors, providing informative messages or fallbacks.
Security: Pay close attention to security best practices, particularly when handling and storing tokens.
Official SDKs: When integrating with third-party APIs, prioritize using official SDKs (e.g., Google APIs, Slack Web API) for better reliability and maintainability.
File Structure: Maintain a consistent and logical file structure for your authorization configurations and tools to improve code organization.