MCP Server — AI Agent API Overview

The SimplerDevelopment portal exposes a Model Context Protocol (MCP) server that lets any MCP-compatible AI client — Claude Code, Claude Desktop, a custom agent — drive your portal programmatically. You can create and publish content, manage projects and CRM records, send campaigns, and more, all from inside your AI environment of choice.

Authentication reminder: See authentication.md for how to issue portal API keys and OAuth tokens. This page covers the transport layer, credential types, scopes, and the approval workflow.

Base URL#

POST https://simplerdevelopment.com/api/mcp

The endpoint accepts Streamable HTTP (stateless JSON-response mode). Each request is independent — there is no persistent session.

Authentication#

Every request must carry a Bearer token in the Authorization header. Two token formats are accepted:

Authorization: Bearer sd_mcp_<64 hex chars>

Both credential types resolve to the same PortalMcpContext (your user identity, your client/company, and your granted scopes). Usage is tracked on every call (lastUsedAt is updated automatically).

If the token is missing, invalid, revoked, or expired, the server returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="simplerdevelopment-mcp", resource_metadata="https://simplerdevelopment.com/.well-known/oauth-protected-resource"

{"jsonrpc":"2.0","error":{"code":-32001,"message":"Unauthorized"}}

Scopes#

Scopes follow the pattern resource:action. A key's scope list is fixed at issuance; the server enforces it per tool call. Attempting to call a tool your key's scopes do not cover silently omits that tool from the registry (the server never registers it), so tools/list only shows tools you can actually use.

Wildcard forms:

Available scopes by domain:

Scopes apply uniformly to every company the connection reaches; what varies per company is your role — see Choosing which company a call acts on.

Approval workflow#

Many write tools in the MCP server do not mutate immediately. Instead they create a draft and return an approval URL. A human reviewer must open that URL and click Approve before the change is published.

This is intentional — it keeps AI-authored content from going live without human sign-off.

How it works#

1. Your agent calls a write tool (e.g. posts_create).
2. The tool creates a draft record, mints a 64-hex-char token, stores it in mcp_approval_links, and returns an approval envelope in the response.
3. You (or your client) open the URL: https://simplerdevelopment.com/approve/<token>.
4. The public page shows a preview. The reviewer clicks Approve or Reject — no portal login required.
5. On approval, the entity is published (or the staged mutation is applied).

Two link types exist:

Approval envelope shape (returned inside tool responses):

{
  "approval": {
    "url": "https://simplerdevelopment.com/approve/a3f8...c1d2",
    "previewUrl": "https://simplerdevelopment.com/approve/a3f8...c1d2",
    "token": "a3f8...c1d2",
    "status": "pending",
    "expiresAt": "2026-06-18T08:37:00.000Z"
  }
}

Approval links expire after 14 days by default. After expiry the link is marked expired and the author must call the corresponding *_update tool to remint a fresh link.

Approvable entity types: post, pitch_deck, email_campaign, block_template, survey, booking_page.

Telemetry and token budget#

Every tool call records latency and token cost via lib/mcp/telemetry.ts. Tool responses are intentionally compact — write tools echo { id, slug, status }, not the full row. Heavy fields (e.g. blocks, html, body) are opt-in via an include flag where supported. This keeps context windows manageable for agents processing many results.

Connecting an AI client#

Claude Desktop / Claude Code#

Add this to your claude_desktop_config.json or Claude Code MCP config:

{
  "mcpServers": {
    "simplerdevelopment": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://simplerdevelopment.com/api/mcp"],
      "env": {
        "MCP_BEARER_TOKEN": "sd_mcp_<your key here>"
      }
    }
  }
}

mcp-remote handles the POST-only transport automatically (it detects the 405 on GET and switches to POST-only mode).

Custom agent (direct HTTP)#

curl -X POST https://simplerdevelopment.com/api/mcp \
  -H "Authorization: Bearer sd_mcp_<your key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Choosing which company a call acts on#

A credential belongs to a user, and a user can belong to several companies. When you authorize a connection you tick which companies it may reach; that set is then intersected with your live team membership on every request, so losing access to a company cuts this connection's access to it immediately, and joining a new company requires re-authorizing.

If the connection reaches one company, nothing changes — every call is scoped to it implicitly.

If it reaches more than one, every tool call takes a clientId naming the company it applies to:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "posts_create",
    "arguments": { "clientId": 19, "title": "Fall promo" }
  }
}

Omit it and the call is refused with the companies listed, rather than being applied to a default:

clientId is required: this credential can act for 3 companies.
  12  Acme Dental (owner)
  19  Beta Roofing (viewer)
  31  Gamma Legal (admin)

Three consequences worth knowing:

• Your role is checked per company. A crm:write scope does not let you write a company where you are only a viewer; scopes describe the connection, roles describe your access to each company.
• A batch may not mix companies. Every tools/call in one batched request must pass the same clientId; send them separately otherwise.
• brand://default and catalog://services are only offered to single-company connections. A resource URI cannot name a company, so multi-company connections read the same data through branding_get_profile / service_catalog_list, which take a clientId.

whoami tool#

Always available — no scope required, and the only tool that never needs a clientId (it is how you discover which ones are valid).

Returns your authenticated user ID, every company the credential can act for with your role on each, the default company, and the scopes your current credential grants.

Tool call:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "whoami",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"userId\":42,\"client\":{\"id\":7,\"company\":\"Acme Corp\"},\"defaultClientId\":7,\"clients\":[{\"id\":7,\"company\":\"Acme Corp\",\"role\":\"owner\"},{\"id\":19,\"company\":\"Beta Roofing\",\"role\":\"viewer\"}],\"scopes\":[\"projects:*\",\"crm:read\",\"sites:write\"]}"
    }]
  }
}

blocks://schema resource#

Always available — no scope required.

An MCP resource (not a tool) that returns the full block-type reference in Markdown. Agents should read this before calling posts_create or posts_update to author valid blocks arrays.

Resource URI: blocks://schema

Fetch via:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": { "uri": "blocks://schema" }
}

Tool domains#

The server registers 450+ tools across 22 product domains, grouped here into six reference pages for readability: