Quickstart Guide

Get your first authenticated and stateful MCP running in under 10 minutes. This guide will take you from zero to a fully functional MCP that can be used in AI agents.

What You'll Build

By the end of this quickstart, you'll have:

A fully authenticated MCP with OAuth integration
Stateful operations with persistent database storage
Example tools, resources, and prompts
A development environment ready for customization

Prerequisites

Node.js 18+ and npm/yarn/pnpm installed
A GitHub account (for OAuth setup)
5-10 minutes of your time

Step-by-Step Guide

Install the Osiris CLI

Install the CLI globally or use npx:

# Install globally (recommended)
npm install -g @osiris-ai/cli

# Or use with npx (no installation needed)
npx @osiris-ai/cli register

The CLI automatically handles OAuth setup, database configuration, and project scaffolding.

Register Your Account

Create your Osiris account:

npx @osiris-ai/cli register

This will:

🔐 Create your secure Osiris account
🌐 Open browser for authentication
💾 Save configuration locally (~/.osiris/config.json)
🔑 Prepare your environment for OAuth clients

You'll be guided through a simple web flow to complete registration.

Create OAuth Client

Set up OAuth credentials for your MCPs:

npx @osiris-ai/cli create-client

This generates:

Client ID and Client Secret for OAuth flows
Callback URLs for authentication redirects
Scopes configuration for service access
Environment setup for your projects

Your OAuth credentials are automatically saved and will be used for all your MCP projects.

Connect Authentication Services

Connect authentication methods to the Osiris Hub:

npx @osiris-ai/cli connect-auth

Choose from available authenticators (OAuth, secret sharing, and wallet-based):

🔗 Productivity

• Google (Gmail, Calendar, Drive)
• GitHub (repos, issues, PRs)
• Linear (projects, tasks)
• Notion (pages, databases)
• Slack (channels, messages)

🌐 Web3 & Data

• Turnkey (secure wallets)
• PostgreSQL (databases)
• MongoDB (NoSQL)
• Redis (caching)

These authentication methods are stored securely in the Osiris Hub. You'll connect them to specific MCPs in the next steps with fine-grained scopes and policies.

Create Your MCP Project

Generate a complete MCP project:

npx @osiris-ai/cli create-mcp

The CLI will prompt you for:

Project name (e.g., my-first-mcp)
Language (TypeScript or JavaScript)
Database adapter (PostgreSQL, MongoDB, Redis, SQLite)
Authentication services to include

This generates a complete project structure:

package.json

.env

.env.example

osiris.json

README.md

tsconfig.json

index.ts

client.ts

Start Development

Navigate to your project and start the development server:

cd my-first-mcp
npm install
npm run dev

Your MCP server is now running at http://localhost:3000 with:

✅ Project structure and dependencies ready
✅ Database connected and migrated
✅ Example tools, resources, and prompts
✅ Hot reload for development

Next Step Required: You still need to connect your hub authentication to this MCP with specific scopes and policies using connect-mcp-auth.

Connect Hub Authentication to Your MCP

Now create a secure, scoped connection between your hub authentication and your MCP:

npx @osiris-ai/cli connect-mcp-auth

This command will:

Select your MCP project from the list of created projects
Choose hub authentication methods to connect (from those you added with connect-auth)
Set specific scopes (e.g., Gmail read/write, GitHub repo access)
Define policies (spending limits for Web3, data access restrictions)
Create secure tokens with limited permissions for your MCP

🎉 Congratulations! Your MCP now has secure, scoped access to user accounts through the Osiris Hub.

Test Your MCP

View Available Commands

Use the CLI to inspect your setup:

# List connected authentication services in the hub
npx @osiris-ai/cli list-auth

# List your MCP projects  
npx @osiris-ai/cli list-mcps

# List active MCP-auth connections with scopes/policies
npx @osiris-ai/cli list-connections

Generated MCP Structure

Your MCP includes these key components:

🔧 Tools (Functions)

Actions your MCP can perform:

• hello_world() - Example tool function
• Authentication context available
• Database access included

📊 Resources (Data)

Information your MCP provides:

• hello_world - Example resource
• User profile data
• Authentication status

Test with Claude Desktop

Add your MCP to Claude Desktop by updating your configuration:

{
  "mcpServers": {
    "my-first-mcp": {
      "type": "streamable-http",
	  "url": "http://localhost:3000/mcp?deploymentId=my-first-mcp"
    }
  }
}

Customize Your MCP

Add a New Tool

Create a new tool with authentication:

// src/tools/email-tool.ts
import { createHubGmailClient } from '@osiris-ai/google-sdk';
import { createMcpServer, getAuthContext } from '@osiris-ai/sdk';

class GmailMCP {
    configureServer(server) {
        server.tool('send_email', 'Send an email through Gmail', {
            to: { type: 'string', description: 'Recipient email' },
            subject: { type: 'string', description: 'Email subject' },
            body: { type: 'string', description: 'Email content' }
        }, async ({ to, subject, body }) => {
            const gmail = this.getGmailClient();
            
            const emailContent = [
                `To: ${to}`,
                `Subject: ${subject}`,
                'MIME-Version: 1.0',
                'Content-Type: text/plain; charset=UTF-8',
                '',
                body
            ];
            
            const raw = Buffer.from(emailContent.join('\r\n'))
                .toString('base64')
                .replace(/\+/g, '-')
                .replace(/\//g, '_');
            
            const result = await gmail.users.messages.send({
                userId: 'me',
                requestBody: { raw }
            });
            
            return {
                content: [{
                    type: 'text',
                    text: `✅ Email sent successfully! Message ID: ${result.data.id}`
                }]
            };
        });
    }
}

Connect to More Services

Connect your hub authentication to your MCP with specific scopes and policies:

# Connect hub authentication to your MCP with controlled access
npx @osiris-ai/cli connect-mcp-auth

# Add more OAuth providers to the hub
npx @osiris-ai/cli connect-auth

Management & Deployment

Update MCP Authentication

Update the authentication connection policies for your MCP:

npx @osiris-ai/cli update-mcp-auth

This allows you to:

Update OAuth scopes for your MCP's access
Modify policy restrictions (spending limits, etc.)
Change which hub authentication methods your MCP can use
Adjust permission levels and data access

Production Deployment

When you're ready to deploy:

Build your MCP: npm run build
Deploy to Osiris Hub: Coming soon with npx @osiris-ai/cli deploy
Share with others: MCPs will be available in the marketplace

🚀 Setup Commands

• register - Create Osiris account
• login - Login to existing account
• create-client - Setup OAuth client
• connect-auth - Connect services to hub

🔧 Development Commands

• create-mcp - Generate MCP project
• connect-mcp-auth - Create scoped auth connection
• update-mcp-auth - Update scopes/policies

📊 Management Commands

• list-auth - Show hub authentication methods
• list-mcps - Show MCP projects
• list-connections - Show MCP-auth connections

🎯 Ready to build something amazing? Start customizing your MCP or explore our comprehensive SDK documentation to unlock advanced features.