Connecting to Our MCP Server using HTTP

Make sure you’ve gone to https://app.observee.ai to obtain your API keys before starting!

MCP API Documentation

cURL Commands

1. Initialize MCP Server

curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "observee-chat-client",
        "version": "1.0.0"
      }
    }
  }'

Response Headers:

mcp-session-id: <generated-session-id>
content-type: text/event-stream

2. Send Initialized Notification

curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'mcp-protocol-version: 2025-06-18' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

3. List Tools

curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

4. Call Tool

curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "TOOL_NAME_FROM_TOOLS_LIST",
      "arguments": {
        "param1": "value1",
        "param2": "value2"
      }
    }
  }'

Example: Gmail Search

curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "Gmail__search_emails",
      "arguments": {
        "query": "from:user@example.com",
        "maxResults": 2
      }
    }
  }'

Example: Everything Calculator

curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "Everything__add",
      "arguments": {
        "a": 5,
        "b": 2
      }
    }
  }'

💡 Finding Tool Arguments: Use the /tools/list endpoint first to get each tool’s inputSchema. This schema defines the required and optional arguments for each tool, including their types, descriptions, and validation rules.

Key Implementation Notes

Authentication

Uses Bearer token authentication with Observee API key
Format: Authorization: Bearer YOUR_API_KEY_HERE

Session Management

Initialize returns mcp-session-id in response headers
Subsequent requests must include this session ID as a header
Session IDs are UUIDs (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)

Response Types

Initialize: Returns text/event-stream (SSE) for real-time updates
Notifications: Returns 202 Accepted with empty body
Tool operations: Return application/json with structured data

McpAuth API - cURL Commands

1. Get Available Servers

Get a list of all supported authentication servers.

curl -X POST 'https://mcpauth.observee.ai/supported_servers' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE"
  }'

Expected Response:

{
  "supportedServers": ["server1", "server2", "server3"]
}

2. Start Auth Flow (Basic)

Start an OAuth flow for a specific service without additional parameters.

curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE"
  }'

3. Start Auth Flow (with Client ID)

Start an OAuth flow with a specific client ID passed as query parameter.

curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start?client_id=YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE"
  }'

4. Start Auth Flow (with Custom Redirect URL)

Start an OAuth flow with a custom redirect URL.

curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE",
    "CUSTOM_REDIRECT_URL": "https://your-app.com/auth/callback"
  }'

5. Start Auth Flow (with Additional Parameters)

Start an OAuth flow with custom parameters for specific auth servers.

curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start?client_id=YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE",
    "CUSTOM_REDIRECT_URL": "https://your-app.com/auth/callback",
    "scopes": "custom-scope-here",
    "workspace": "your-workspace"
  }'

Server Discovery

Replace <server> in the auth flow URLs with any server name from the supportedServers array returned by the /supported_servers endpoint above.

Expected Auth Flow Response

{
  "auth_url": "https://accounts.google.com/oauth/authorize?client_id=...",
  "state": "random-state-string",
  "expires_in": 3600,
  "callback_url": "https://mcpauth.observee.ai/callback"
}

Error Response Example

{
  "error": "Invalid API key",
  "status": 401
}

Usage Flow

Get available servers to see what services are supported
Start auth flow for your desired service
Redirect user to the auth_url from the response
Handle callback when user completes OAuth flow
Use the authenticated credentials in your MCP tools

Notes

All requests use POST method
API key is always required in the request body as OBSERVEE_API_KEY
Client ID is optional and passed as query parameter
Custom parameters go in the request body
The auth flow returns a URL where users complete OAuth authentication

Get Started

MCP Provider Integrations

MCP Agents SDK

MCP Auth SDK

MCP Logger SDK

Examples

Connecting to Our MCP Server using HTTP

MCP API Documentation

cURL Commands

1. Initialize MCP Server

2. Send Initialized Notification

3. List Tools

4. Call Tool

Example: Gmail Search

Example: Everything Calculator

Key Implementation Notes

Authentication

Session Management

Response Types

McpAuth API - cURL Commands

1. Get Available Servers

2. Start Auth Flow (Basic)

3. Start Auth Flow (with Client ID)

4. Start Auth Flow (with Custom Redirect URL)

5. Start Auth Flow (with Additional Parameters)

Server Discovery

Expected Auth Flow Response

Error Response Example

Usage Flow

Notes

​MCP API Documentation

​cURL Commands

​1. Initialize MCP Server

​2. Send Initialized Notification

​3. List Tools

​4. Call Tool

​Example: Gmail Search

​Example: Everything Calculator

​Key Implementation Notes

​Authentication

​Session Management

​Response Types

​McpAuth API - cURL Commands

​1. Get Available Servers

​2. Start Auth Flow (Basic)

​3. Start Auth Flow (with Client ID)

​4. Start Auth Flow (with Custom Redirect URL)

​5. Start Auth Flow (with Additional Parameters)

​Server Discovery

​Expected Auth Flow Response

​Error Response Example

​Usage Flow

​Notes

MCP API Documentation

cURL Commands

1. Initialize MCP Server

2. Send Initialized Notification

3. List Tools

4. Call Tool

Example: Gmail Search

Example: Everything Calculator

Key Implementation Notes

Authentication

Session Management

Response Types

McpAuth API - cURL Commands

1. Get Available Servers

2. Start Auth Flow (Basic)

3. Start Auth Flow (with Client ID)

4. Start Auth Flow (with Custom Redirect URL)

5. Start Auth Flow (with Additional Parameters)

Server Discovery

Expected Auth Flow Response

Error Response Example

Usage Flow

Notes