Skip to main content
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"  }  }  }' 
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:[email protected]",  "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

  1. Initialize returns mcp-session-id in response headers
  2. Subsequent requests must include this session ID as a header
  3. 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

  1. Get available servers to see what services are supported
  2. Start auth flow for your desired service
  3. Redirect user to the auth_url from the response
  4. Handle callback when user completes OAuth flow
  5. 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