MCP Server

Overview

The Model Context Protocol (MCP) is an open standard that lets AI assistants (Claude Desktop, Cursor, Cline, custom agents, and more) call external tools. Setu hosts a remote MCP server, so any compatible client can send messages, manage conversations and groups, search users, upload files, and manage webhooks — all on behalf of the user that owns the API key.

Connection

Every request must carry a bearer token. Setu supports two ways to obtain one — a long-lived static API key or an OAuth 2.1 access token. Both authenticate as a single Setu user and are constrained by the same permission scopes and rate limits. See Authentication to pick the right one.

Authentication

The MCP server accepts two authentication methods. Both resolve to the same Setu user, the same permission scopes, and the same rate limits — pick based on your client and who the agent acts for.

Option A — Static Bearer Token (API key)

The simplest method. Create a key in API Keys, grant it the scopes you want the agent to use, and send it on every request:

Authorization: Bearer tap_setu_YOUR_KEY_HERE

Keys start with tap_setu_ and are long-lived (they only stop working if you disable them or set an expiry). The full key is shown once at creation — store it immediately. This is the right choice when you own both the agent and the account it acts as. See Client Setup for ready-to-paste config.

Option B — OAuth 2.1

Use OAuth when an agent or app needs to act on behalf of a user without ever handling a static key. The user authorizes through a Setu consent screen and your client receives a scoped, expiring access token. Setu implements OAuth 2.1 with mandatory PKCE (S256) and Dynamic Client Registration.

Discovery

Clients discover the endpoints from the standard metadata document (RFC 8414):

GET https://setu.theabhipatel.com/.well-known/oauth-authorization-server

{
  "issuer": "https://setu.theabhipatel.com",
  "authorization_endpoint": "https://setu.theabhipatel.com/oauth/authorize",
  "token_endpoint": "https://setu.theabhipatel.com/api/oauth/token",
  "registration_endpoint": "https://setu.theabhipatel.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post"]
}

Step 1 — Register a client (RFC 7591)

Register once to get a client_id. No authentication is required. Redirect URIs must be localhost or HTTPS.

curl -X POST https://setu.theabhipatel.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My MCP Client",
    "redirect_uris": ["http://localhost:9999/oauth/callback"],
    "grant_types": ["authorization_code"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none",
    "scope": "messages:send messages:read conversations:read"
  }'

{
  "client_id": "setu_oac_...",
  "redirect_uris": ["http://localhost:9999/oauth/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Public clients use token_endpoint_auth_method: "none" (no secret). For a confidential client, use client_secret_post and a client_secret (prefix setu_ocs_) is returned.

Step 2 — Authorize (with PKCE)

Generate a PKCE code_verifier and its S256 code_challenge, then send the user to the authorization endpoint in a browser:

GET https://setu.theabhipatel.com/oauth/authorize
  ?client_id=setu_oac_...
  &redirect_uri=http://localhost:9999/oauth/callback
  &response_type=code
  &scope=messages:send%20messages:read%20conversations:read
  &state=RANDOM_CSRF_VALUE
  &code_challenge=PKCE_S256_CHALLENGE
  &code_challenge_method=S256

The user signs in (if needed) and approves the requested scopes. Setu then redirects back to your redirect_uri with a one-time authorization code (the state is echoed back — verify it):

http://localhost:9999/oauth/callback?code=setu_ocd_...&state=RANDOM_CSRF_VALUE

Step 3 — Exchange the code for tokens

POST the code and the original code_verifier to the token endpoint (accepts JSON or x-www-form-urlencoded):

curl -X POST https://setu.theabhipatel.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "setu_ocd_...",
    "client_id": "setu_oac_...",
    "redirect_uri": "http://localhost:9999/oauth/callback",
    "code_verifier": "YOUR_PKCE_VERIFIER"
  }'

{
  "access_token": "setu_oat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "setu_ort_...",
  "scope": "messages:send messages:read conversations:read"
}

Step 4 — Call the MCP server

Send the access token exactly like a static key — same header, same tools:

Authorization: Bearer setu_oat_...

Step 5 — Refresh when it expires

Access tokens last 1 hour; refresh tokens last 30 days. When an access token expires, exchange the refresh token for a new pair (the old refresh token is rotated out):

curl -X POST https://setu.theabhipatel.com/api/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "setu_ort_...",
    "client_id": "setu_oac_..."
  }'

Client Setup

The snippets below use a static API key. If your client supports OAuth, you can instead point it at the URL with no header and it will run the OAuth flow for you in the browser:

{
  "mcpServers": {
    "setu-chat": {
      "url": "https://setu.theabhipatel.com/api/mcp"
    }
  }
}

Clients with native remote MCP support (e.g. Cursor)

Point the client at the URL and attach the auth header:

{
  "mcpServers": {
    "setu-chat": {
      "url": "https://setu.theabhipatel.com/api/mcp",
      "headers": {
        "Authorization": "Bearer tap_setu_YOUR_KEY_HERE"
      }
    }
  }
}

Claude Desktop / stdio-only clients

Use the mcp-remote bridge to connect a stdio client to the remote server with headers:

{
  "mcpServers": {
    "setu-chat": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://setu.theabhipatel.com/api/mcp",
        "--header", "Authorization: Bearer tap_setu_YOUR_KEY_HERE"
      ]
    }
  }
}

Test it with the MCP Inspector

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: https://setu.theabhipatel.com/api/mcp
# Header: Authorization: Bearer tap_setu_YOUR_KEY_HERE

Tools Reference

Parameters marked * are required. Each tool requires the listed permission scope on your API key; calling a tool without its scope returns a PERMISSION_DENIED error.

Example Prompts

Once connected, you can drive Setu in natural language. The agent picks the right tools automatically:

Rate Limits

MCP tool calls share the exact same rate limit and usage tracking as the REST API — each tool call counts as a single request against your key's per-minute limit. See the REST docs for per-plan limits, and Usage & Analytics to monitor consumption.

Troubleshooting