Building Custom Agents

Prefer writing your own agent to using Zapier or n8n? The REST API, OpenAPI spec, and outbound webhooks give you everything you need.

Core building blocks

1. Personal access token — mint with narrow abilities. See authentication.
2. OpenAPI spec — https://api.memberpass.net/openapi.json. Feed it to your favourite code-gen tool (openapi-generator, Stainless, Speakeasy).
3. Typed SDK — optional; a generated client beats hand-rolled fetch calls once your surface gets non-trivial.
4. Outbound webhooks — for event-driven work. Sign-verify per security guide.
5. Idempotency — every write takes Idempotency-Key. Your SDK should inject a UUID automatically.

Suggested architecture

┌──────────────┐          ┌──────────────────────┐          ┌───────────────┐
│   Your app   │◀─webhook─│  MemberPass API      │◀─REST────│  Your agent   │
│              │  (POST)  │  api.memberpass.net  │          │  (LLM + tools)│
└──────────────┘          └──────────────────────┘          └───────────────┘

• Your agent pushes commands to MemberPass over REST.
• MemberPass pushes state changes back to your app over outbound webhooks.
• The agent can observe state either by polling GET endpoints or by subscribing to its own webhook inbox.

Read-first, write-later

Most agents should start in read-only mode:

• Token abilities: project:view-any, project-user:view-any, project-subscription-plan:view-any.
• Build and test the retrieval + summary pipeline.
• Only then mint a second token with write abilities and enable the write paths.

Keeping read and write tokens separate limits blast radius on a leak.

Retry and back-off policy

• Always retry on 5xx and 429 with exponential back-off.
• Honour Retry-After when present.
• Use the same Idempotency-Key across retries of the same logical operation so replays are free.

Surfacing errors to the user

MemberPass returns structured errors:

{
  "error": {
    "code": "TOKEN_MISSING_ABILITY",
    "message": "...",
    "docs_url": "https://docs.memberpass.net/api/errors#TOKEN_MISSING_ABILITY",
    "remediation": "Mint a new token that includes the required ability.",
    "request_id": "..."
  }
}

Echo code, message, and docs_url into your agent's failure output. The request_id is worth passing back to support if you need help diagnosing a specific call.

Observing your agent's actions

Every REST call and MCP tool invocation is logged under activity_log with actor_kind = 'api_token' or 'mcp'. Review in the dashboard, or fetch via GET /v1/activity.

When to use MCP instead

If the agent is a Claude-family model, MCP gives you typed tool-calls and first-class ability enforcement without an OpenAPI layer. Use MCP for Claude Desktop / Cursor; use the raw REST API when you're running inference on OpenAI, Google, Mistral, or self-hosted models.