What is Mcp Oauth Provider

mcp-oauth-provider is a TypeScript implementation of an OAuth provider specifically designed for Ory MCP, supporting both Ory Network and Ory Hydra as backend providers.

Use cases

Use cases include integrating OAuth 2.0 authentication in web applications, mobile applications, and microservices architectures, where secure authorization and user identity management are essential.

How to use

To use mcp-oauth-provider, install it via npm with ‘npm install @ory/mcp-oauth-provider’. Then, initialize the OryProvider with either Ory Network or Ory Hydra configuration, specifying the necessary endpoints and API keys.

Key features

Key features include support for multiple backend providers (Ory Network and Ory Hydra), TypeScript implementation for type safety, a comprehensive test suite, and example implementations for easy setup.

Where to use

mcp-oauth-provider can be used in applications requiring OAuth 2.0 authentication, particularly in environments leveraging Ory Network or Ory Hydra for identity management.

Ory MCP OAuth Provider

A TypeScript implementation of an OAuth provider for Ory MCP that supports both Ory Network and Ory Hydra as backend providers.

Installation

npm install @ory/mcp-oauth-provider

Project Structure

mcp-oauth-provider/
├── src/                    # Source code directory
│   ├── example/           # Example implementations
│   │   └── mcp-server.ts  # Complete MCP server example
│   ├── index.ts           # Main implementation
│   └── index.test.ts      # Test suite
├── dist/                  # Compiled output
├── package.json          # Project configuration and dependencies
├── tsconfig.json         # TypeScript configuration
├── tsup.config.ts        # Build configuration
└── vitest.config.ts      # Test configuration

The project is organized as a TypeScript library with the following key components:

• src/index.ts: Contains the main OryProvider implementation
• src/example/: Contains example implementations, including a complete MCP server setup
• src/index.test.ts: Comprehensive test suite for the provider
• Configuration files for TypeScript, testing, and building

Usage

Basic Setup

import { OryProvider, OryOptions } from '@ory/mcp-oauth-provider';

// Initialize with Ory Network
const networkProvider = new OryProvider({
  providerType: 'network',
  networkProjectUrl: 'https://your-project.projects.oryapis.com',
  networkProjectApiKey: 'your-api-key',
  endpoints: {
    authorizationUrl: 'https://your-project.projects.oryapis.com/oauth2/auth',
    tokenUrl: 'https://your-project.projects.oryapis.com/oauth2/token',
    revocationUrl: 'https://your-project.projects.oryapis.com/oauth2/revoke',
    registrationUrl: 'https://your-project.projects.oryapis.com/admin/clients',
  },
});

// Or initialize with Ory Hydra
const hydraProvider = new OryProvider({
  providerType: 'hydra',
  hydraAdminUrl: 'https://hydra.example.com/admin',
  hydraApiKey: 'your-hydra-api-key',
  endpoints: {
    authorizationUrl: 'https://hydra.example.com/oauth2/auth',
    tokenUrl: 'https://hydra.example.com/oauth2/token',
    revocationUrl: 'https://hydra.example.com/oauth2/revoke',
    registrationUrl: 'https://hydra.example.com/admin/clients',
  },
});

MCP Server Integration

Here’s a complete example of how to set up an MCP server with Ory authentication:

import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
import { mcpAuthRouter } from '@modelcontextprotocol/sdk/server/auth/router.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import { config } from 'dotenv';
import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { OryProvider } from '@ory/mcp-oauth-provider';

// Load environment variables
config();

// Get configuration from environment variables
const oryProjectUrl = process.env.ORY_PROJECT_URL;
const oryProjectApiKey = process.env.ORY_PROJECT_API_KEY;
const mcpBaseUrl = process.env.MCP_BASE_URL;
const serviceDocumentationUrl = process.env.SERVICE_DOCUMENTATION_URL;

// Validate required environment variables
if (!oryProjectUrl || !oryProjectApiKey || !mcpBaseUrl || !serviceDocumentationUrl) {
  throw new Error('Required environment variables are not set');
}

// Initialize the Ory provider
const oryProvider = new OryProvider({
  providerType: 'network',
  networkProjectUrl: oryProjectUrl,
  networkProjectApiKey: oryProjectApiKey,
  endpoints: {
    authorizationUrl: `${oryProjectUrl}/oauth2/auth`,
    tokenUrl: `${oryProjectUrl}/oauth2/token`,
    revocationUrl: `${oryProjectUrl}/oauth2/revoke`,
    registrationUrl: `${oryProjectUrl}/oauth2/register`,
  },
});

// Create Express app
const app = express();
app.use(express.json());

// Set up MCP authentication router
app.use(
  mcpAuthRouter({
    provider: oryProvider,
    issuerUrl: new URL(oryProjectUrl),
    baseUrl: new URL(mcpBaseUrl),
    serviceDocumentationUrl: new URL(serviceDocumentationUrl),
  })
);

// Set up bearer auth middleware
const bearerAuthMiddleware = requireBearerAuth({
  provider: oryProvider,
  requiredScopes: ['ory.admin'],
});

// Create MCP server
const server = new McpServer(
  {
    name: 'ory-mpc-example',
    version: '1.0.0',
    description: 'Example MPC server with Ory authentication',
  },
  { capabilities: { logging: {} } }
);

// Handle MCP requests
app.post('/mcp', bearerAuthMiddleware, async (req, res) => {
  const transport = new StreamableHTTPServerTransport();
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
  res.on('close', () => {
    transport.close();
    server.close();
  });
});

// Start the server
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`MCP server listening on port ${port}`);
});

Key Features

• Supports both Ory Network and Ory Hydra as backend providers
• Handles OAuth2 authorization code flow with PKCE
• Manages client registration and token operations
• Provides token introspection and verification
• Integrates seamlessly with MCP server

Development

1. Clone the repository
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

4. Run tests:

   npm test
   

License

Copyright 2025 Ory Corp

Licensed under the Apache License, Version 2.0 (the “License”);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an “AS IS” BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.