serenities AI

MCP Protocol

Integrate Serenities with AI platforms using the Model Context Protocol.

MCP Endpoint

https://app.serenitiesai.com/api/v1/mcp

All MCP requests use POST with JSON-RPC 2.0 format.

Authentication

Serenities MCP supports two authentication methods:

Option 1: API Key (Simple)

Create an API key in your account settings and use it in the Authorization header:

Authorization: Bearer mk_live_your_api_key

Option 2: OAuth 2.1 (Automatic)

MCP clients that support OAuth can connect without an API key. Simply add the server URL and you'll be prompted to login via your browser when the client connects.

OAuth Discovery: https://app.serenitiesai.com/.well-known/oauth-authorization-server
Authorization: https://app.serenitiesai.com/api/mcp-oauth/authorize
Token Endpoint: https://app.serenitiesai.com/api/mcp-oauth/token
Registration: https://app.serenitiesai.com/api/mcp-oauth/register
PKCE Required: S256

OAuth tokens use the mcp_at_ prefix and expire after 1 hour. Refresh tokens are automatically used to get new access tokens.

Core Methods

initialize

Initialize the MCP session. Returns server capabilities and protocol version.

tools/list

List all available tools with their input schemas.

tools/call

Execute a specific tool with the provided arguments.

Example: List Tools

curl -X POST https://app.serenitiesai.com/api/v1/mcp \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Example: Call Tool

curl -X POST https://app.serenitiesai.com/api/v1/mcp \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tables_listBases",
      "arguments": {}
    }
  }'

Connect to AI Platforms

Most modern AI tools now support native HTTP/SSE transport for remote MCP servers. Only Claude Desktop (via config file) still requires mcp-remote.

Native HTTP/SSE
Most tools support this - No mcp-remote needed

Claude Code, Cursor, Windsurf, VS Code Continue, and VS Code Copilot all support HTTP transport directly.

Claude Code (CLI)

Native HTTP

Add with one command:

claude mcp add serenities \
  --transport http \
  --url https://app.serenitiesai.com/api/v1/mcp \
  --header "Authorization: Bearer mk_live_your_api_key"

Or edit ~/.claude.json directly:

{
  "projects": {
    "/your/project/path": {
      "mcpServers": {
        "serenities": {
          "type": "http",
          "url": "https://app.serenitiesai.com/api/v1/mcp",
          "headers": {
            "Authorization": "Bearer mk_live_your_api_key"
          }
        }
      }
    }
  }
}

After adding, restart Claude Code or start a new session. Tools appear as mcp__serenities__*.

Cursor

Native HTTP/SSE

Cursor supports SSE and Streamable HTTP natively. Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "serenities": {
      "url": "https://app.serenitiesai.com/api/v1/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer mk_live_your_api_key"
      }
    }
  }
}

Windsurf / Codeium

Native HTTP/SSE

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "serenities": {
      "serverUrl": "https://app.serenitiesai.com/api/v1/mcp",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer mk_live_your_api_key"
      }
    }
  }
}

VS Code (Continue Extension)

Native Streamable HTTP

Create ~/.continue/mcpServers/serenities.yaml:

name: Serenities
version: 0.0.1
schema: v1
mcpServers:
  - name: serenities
    type: streamable-http
    url: https://app.serenitiesai.com/api/v1/mcp
    headers:
      Authorization: Bearer mk_live_your_api_key

VS Code (Copilot / Native)

Native HTTP

Add to VS Code settings or .vscode/mcp.json:

{
  "servers": {
    "serenities": {
      "type": "http",
      "url": "https://app.serenitiesai.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer mk_live_your_api_key"
      }
    }
  }
}
mcp-remote required
Only for Claude Desktop config file

Claude Desktop config file only supports stdio. Use npx mcp-remote as a bridge.
(Pro/Max/Team users can add remote servers via Settings → Connectors instead)

Claude Desktop

mcp-remote

Edit your config file (or use Settings → Connectors for Pro/Max/Team plans):

{
  "mcpServers": {
    "serenities": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.serenitiesai.com/api/v1/mcp",
        "--header",
        "Authorization: Bearer ${API_KEY}"
      ],
      "env": {
        "API_KEY": "mk_live_your_api_key"
      }
    }
  }
}

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Any MCP Client (Generic)

Use these connection details for any MCP-compatible client:

Server URL: https://app.serenitiesai.com/api/v1/mcp
Transport: HTTP (POST with JSON-RPC 2.0)
Auth Header: Authorization: Bearer mk_live_your_api_key
Content-Type: application/json

Tip: If your MCP client supports native HTTP transport, use it directly. If it only supports stdio, use npx mcp-remote as a bridge.

Quick Setup Steps

1

Create an API Key

Go to Account → API Keys and create a new key with the permissions you need.

2

Copy Your API Key

Copy the key immediately - it will only be shown once!

3

Add to Your AI Tool

Paste the configuration above into your AI tool's MCP config file.

4

Restart Your AI Tool

Restart Claude Desktop, Cursor, or VS Code to connect to Serenities.

MCP Protocol Documentation - Serenities