Call Workspace369 from your app over HTTPS

Your own server code can call the same tools an AI app uses. You send an HTTPS POST to the Workspace369 MCP endpoint with a personal access token, and get one JSON answer back. This is the Model Context Protocol over HTTP, not a REST API: there is one URL, and the tool name goes in the request body.

Use this from a backend, a scheduled job, or a script. Do not call it from browser code.

Before you begin

1. A workspace admin has turned MCP on. See Enable MCP and manage connected apps.
2. You have a personal access token with the scopes your calls need. See Personal access tokens for scripts and agents.
3. The token is in an environment variable on your server, here called WORKSPACE369_TOKEN.

How the endpoint works

• URL: https://mcp.workspace369.com/mcp. To pin requests to one workspace, use https://mcp.workspace369.com/w/<workspaceId>/mcp. A token for a different workspace is refused with a 403.
• Method: POST only. Any other method returns 405.
• Stateless: every request stands alone. There is no session to open or close, and each answer is a single JSON body.
• Headers: Authorization: Bearer <token>, Content-Type: application/json, and Accept: application/json, text/event-stream. The Accept header must list both types.
• Body: a JSON-RPC 2.0 message, up to 1 MB.
• Token: a personal access token starts with mcp_pat_.

List the tools

tools/list returns every tool you can call, with its description and input schema.

curl -s https://mcp.workspace369.com/mcp \
  -H "Authorization: Bearer $WORKSPACE369_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

The answer has the form {"jsonrpc":"2.0","id":1,"result":{"tools":[ ... ]}}. Each tool has a name, a description, and an inputSchema that tells you which arguments it accepts. Read the schema before you call a tool. The same list is in the MCP tools reference.

Call a tool

tools/call takes the tool name and its arguments. This call searches clients:

curl -s https://mcp.workspace369.com/mcp \
  -H "Authorization: Bearer $WORKSPACE369_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "clients_search",
      "arguments": { "query": "Acme", "limit": 10 }
    }
  }'

A successful answer looks like this:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{ "type": "text", "text": "Found 1 client ..." }],
    "structuredContent": { "clients": [ ... ], "nextCursor": "..." }
  }
}

Read result.structuredContent in code. result.content is the same information as text for a person or model to read.

Node.js

This helper works in Node 18 and later. It retries once after a rate limit and returns the structured result.

const ENDPOINT = "https://mcp.workspace369.com/mcp";

let nextId = 1;

export async function callTool(name, args = {}) {
  for (let attempt = 0; attempt < 2; attempt++) {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.WORKSPACE369_TOKEN}`,
        "Content-Type": "application/json",
        Accept: "application/json, text/event-stream",
      },
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: nextId++,
        method: "tools/call",
        params: { name, arguments: args },
      }),
    });

    if (res.status === 429) {
      const wait = Number(res.headers.get("Retry-After") ?? "5");
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    if (res.status === 401) throw new Error("Token is invalid, revoked, or expired.");
    if (!res.ok) throw new Error(`Workspace369 returned HTTP ${res.status}`);

    const body = await res.json();
    if (body.error) throw new Error(`JSON-RPC error ${body.error.code}: ${body.error.message}`);

    const result = body.result;
    if (result.isError) {
      throw new Error(result.content?.[0]?.text ?? "The tool refused the call.");
    }
    if (result.structuredContent?.held_for_approval) {
      return { held: true, ...result.structuredContent };
    }
    return result.structuredContent;
  }
  throw new Error("Rate limited twice in a row.");
}

Python

import os
import time
import requests

ENDPOINT = "https://mcp.workspace369.com/mcp"
_next_id = 0


def call_tool(name, arguments=None):
    global _next_id
    for _ in range(2):
        _next_id += 1
        res = requests.post(
            ENDPOINT,
            headers={
                "Authorization": f"Bearer {os.environ['WORKSPACE369_TOKEN']}",
                "Content-Type": "application/json",
                "Accept": "application/json, text/event-stream",
            },
            json={
                "jsonrpc": "2.0",
                "id": _next_id,
                "method": "tools/call",
                "params": {"name": name, "arguments": arguments or {}},
            },
            timeout=60,
        )
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", "5")))
            continue
        if res.status_code == 401:
            raise RuntimeError("Token is invalid, revoked, or expired.")
        res.raise_for_status()

        body = res.json()
        if "error" in body:
            raise RuntimeError(f"JSON-RPC error: {body['error']}")
        result = body["result"]
        if result.get("isError"):
            raise RuntimeError(result["content"][0]["text"])
        structured = result.get("structuredContent") or {}
        if structured.get("held_for_approval"):
            return {"held": True, **structured}
        return structured
    raise RuntimeError("Rate limited twice in a row.")

Handle errors

There are two layers of errors. HTTP status codes describe the request. The isError flag on a result describes the tool call.

Typical isError reasons are "MCP is not enabled for this workspace", "Insufficient scope", a missing permission, a record that was not found, an opted-out client, and an out-of-allowance message when the workspace cannot pay for the call. A refused or failed call is not charged.

Calls held for approval

Tools that send something to a person are held until someone approves them in the Workspace369 app. A held call is not an error. The result looks like this:

{
  "structuredContent": {
    "held_for_approval": true,
    "approval_id": "...",
    "approval_url": "https://app.workspace369.com/settings/approvals/...",
    "approval_expires_at": "2026-10-18T15:00:00.000Z"
  }
}

Nothing has been sent. Do not call the tool again for the same request, because a second call would create a second request. Instead:

1. Show the person the approval_url, or tell them to open Approvals in Workspace369.
2. Poll approvals_get with { "approval_id": "..." }. It is free. Its status is pending, executing, approved_done, declined, expired, failed, or interrupted, and outcome holds the result once the call has run.
3. If the status is interrupted, do not repeat the call. It may already have gone out. Ask the person to check the app.

A request expires after 1 hour. The full list of tools that are held is in How MCP access is controlled and billed.

Rate limits

One connection may make 120 calls per minute. The whole workspace may make 600 calls per minute. A call over the limit gets a 429 with Retry-After and is not counted against the next minute. If you need many records, ask for larger pages with the tool's limit and cursor arguments instead of many small calls.

Write tools accept an optional idempotency_key. Send the same key again to avoid doing the same thing twice after a network error.

Check your result

1. Run the tools/list request. You should see a list of tools.
2. Run a read-only tools/call, such as clients_search. You should see structuredContent.
3. Revoke the token and run the request again. You should get a 401.
4. Open AI Connections (MCP) in Settings and find your calls in the Activity Log.