Ontraport MCP Server

A stateless Node.js service that implements the Model Context Protocol (MCP) to expose Ontraport CRM functionality as structured tools consumable by any MCP-compatible AI agent.

The server is a translation layer. It receives tool calls from AI agents, authenticates them against Ontraport API credentials, translates them into the appropriate Ontraport REST API calls, cleans the responses, and returns structured results. It contains no business logic of its own.

Table of Contents

• Architecture

• Getting Started

• Authentication

• How It Works

  • Request Lifecycle

  • Dynamic Manifest Generation

  • Tool Execution

  • Response Cleaning

• Project Structure

• Tool Reference

  • Contacts (7 tools)

  • Tags (6 tools)

  • Sequences & Campaigns (4 tools)

  • Tasks (5 tools)

  • Notes (2 tools)

  • Messages (2 tools)

  • Purchases & Orders (5 tools)

  • Transactions Write (13 tools)

  • Products (2 tools)

  • Custom Objects (4 tools per object)

  • Metadata & Discovery (2 tools)

• Input Reference

  • Condition Parameter

  • Pagination

  • Timestamps

  • List Selection Fields

• Error Handling

• Manifest Size Guard

• Rate Limiting

• Security

• Testing

• Configuration

• What Is Excluded from v1

Related MCP server: Attio MCP Server

Architecture

┌─────────────────┐       ┌──────────────────────────┐       ┌──────────────────┐
│                 │       │   Ontraport MCP Server   │       │                  │
│   AI Agent      │──────▶│                          │──────▶│  Ontraport API   │
│  (any MCP       │  POST │  1. Validate auth        │  HTTP │                  │
│   compatible)   │  /v1  │  2. Route JSON-RPC       │       │  api.ontraport   │
│                 │◀──────│  3. Translate to REST     │◀──────│  .com/1/...      │
│                 │       │  4. Clean response        │       │                  │
└─────────────────┘       └──────────────────────────┘       └──────────────────┘

Key properties:

• Built on the official MCP SDK — Uses @modelcontextprotocol/sdk with StreamableHTTPServerTransport for protocol-compliant transport and session management.

• Stateless — No database, no persistent session storage, no caching. All state lives in Ontraport. In-memory sessions track only the MCP transport lifecycle.

• Full MCP endpoint — POST /v1 for requests, GET /v1 for SSE notification streams, DELETE /v1 for session termination. Plus GET /v1/health for monitoring.

• Per-session isolation — Each agent connection gets its own Server + Transport pair scoped to its credentials. No cross-session state leakage.

• Dynamic manifest — The tool list is generated fresh on every tools/list call by querying the Ontraport account's object metadata.

• Credential passthrough — The server forwards Api-Key and Api-Appid headers directly to the Ontraport API. It never stores, caches, or logs credentials.

Getting Started

Prerequisites

• Node.js 18+ (uses native fetch)

Install & Run

npm install
npm start

The server starts on port 3000 by default. Set the PORT environment variable to change it.

Health Check

curl http://localhost:3000/v1/health
# {"status":"ok"}

This endpoint requires no authentication and is intended for uptime monitoring.

Quick Test — Initialize

curl -X POST http://localhost:3000/v1 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Api-Key: YOUR_API_KEY" \
  -H "Api-Appid: YOUR_APP_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"},"capabilities":{}}}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "serverInfo": { "name": "ontraport-mcp-server", "version": "1.0.0" },
    "capabilities": { "tools": {} }
  }
}

Authentication

Every request to POST /v1 must include two HTTP headers:

If either header is missing, the server responds with HTTP 401 before making any downstream calls.

The server passes these credentials directly to the Ontraport API on every call. Permission scoping is enforced by Ontraport's existing API key scope system — if a key lacks a required scope, the Ontraport API returns an error and the MCP server surfaces it cleanly.

How It Works

Request Lifecycle

Every request follows the same path:

Agent sends JSON-RPC request to POST /v1
  ↓
Express validates Api-Key + Api-Appid headers (401 if missing)
  ↓
Looks up or creates a session (Server + StreamableHTTPServerTransport pair)
  ↓
SDK handles JSON-RPC framing, protocol negotiation, and method routing:
  • initialize     → returns server info + capabilities (handled by SDK)
  • tools/list     → our handler builds dynamic manifest via /objects/meta
  • tools/call     → our handler dispatches to tool implementation
  ↓
Tool handler:
  1. Validates input parameters
  2. Constructs Ontraport API request
  3. Executes via OntraportClient with provided credentials
  4. Cleans response (strips noise fields)
  5. Returns structured result

The SDK's StreamableHTTPServerTransport handles the full MCP Streamable HTTP spec including session management (Mcp-Session-Id header), SSE streaming for server notifications (GET /v1), and session termination (DELETE /v1).

Dynamic Manifest Generation

Not all Ontraport accounts have the same objects. Customers can create custom objects, each with its own API endpoints and unique object type ID. Because of this, the tool manifest cannot be static.

When an agent calls tools/list, the server:

1. Calls GET /objects/meta on the Ontraport API using the agent's credentials

2. Identifies custom objects (anything not in the built-in object type ID list)

3. Generates 4 tool definitions per custom object (get_, create_, update_, search_)

4. Merges the 48 static tools with the dynamically generated custom object tools

5. Enforces the 100-tool manifest cap (see Manifest Size Guard)

6. Returns the complete tool list

The manifest is never cached. Every tools/list call triggers a fresh /objects/meta request so the manifest always reflects the current state of the account.

If the /objects/meta call fails (bad credentials, Ontraport outage), the server returns an MCP error — it never returns a partial manifest.

Tool Execution

When an agent calls tools/call, the server:

1. Looks up the tool name in the static handler registry

2. If not found, checks if the name matches a custom object pattern (get_X, create_X, update_X, search_X)

3. For custom object tools, calls /objects/meta to resolve the object's type ID dynamically — this means tools/call works independently of any prior tools/list call

4. Executes the handler, which translates the tool parameters into the appropriate Ontraport REST API call

5. Cleans the response and returns it in the MCP content format

This design is fully stateless — there is no global mutable state, no dependency between tools/list and tools/call, and concurrent requests from different accounts are safe.

Response Cleaning

Before returning Ontraport API responses to agents, the server strips fields that add noise without value:

• system_source

• source_location

• import_id

• bindex

• ip_addy (deprecated)

• ip_addy_display

• contact_cat (deprecated)

• updateSequence (deprecated)

• updateCampaign (deprecated)

• account_id (the agent already knows which account it's connected to)

Cleaning is applied recursively to nested objects and arrays.

Project Structure

src/
├── index.js                        # Express app: auth, session management, HTTP routing
├── errors.js                       # Structured error builders (400–500 taxonomy)
├── mcp/
│   └── server.js                   # MCP Server factory: creates per-session Server instances
│                                   #   with tools/list and tools/call handlers registered
├── manifest/
│   ├── static-tools.js             # All 42 static tool definitions (single source of truth)
│   ├── custom-object-tools.js      # Generates 4 tools per custom object
│   ├── builder.js                  # Merges static + dynamic tools, enforces 100-tool cap
│   └── builder-constants.js        # Built-in object type IDs (shared constant)
├── ontraport/
│   ├── client.js                   # HTTP client for the Ontraport REST API
│   └── response-cleaner.js         # Strips noise fields from API responses
└── tools/
    ├── registry.js                 # Tool name → handler dispatch (static + dynamic resolution)
    ├── contacts.js                 # 7 contact tools
    ├── tags.js                     # 6 tag tools
    ├── sequences.js                # 4 sequence/campaign tools
    ├── tasks.js                    # 5 task tools
    ├── notes.js                    # 2 note tools
    ├── messages.js                 # 2 message tools
    ├── purchases.js                # 5 purchase/order read tools
    ├── transactions.js             # 13 transaction write tools
    ├── products.js                 # 2 product tools
    ├── custom-objects.js           # Generic CRUD handlers for custom objects
    └── metadata.js                 # 2 metadata/discovery tools

test/
├── health.test.js                  # Health endpoint
├── auth.test.js                    # Authentication validation (SDK transport)
├── mcp-server.test.js              # MCP Server factory
├── error-handling.test.js          # Error taxonomy
├── response-cleaner.test.js        # Response cleaning
├── manifest.test.js                # Manifest generation, cap, truncation
└── tools/
    ├── contacts.test.js
    ├── tags.test.js
    ├── sequences.test.js
    ├── tasks.test.js
    ├── notes.test.js
    ├── messages.test.js
    ├── purchases.test.js
    ├── transactions.test.js
    ├── products.test.js
    ├── custom-objects.test.js
    └── metadata.test.js

Design Principles

• Single source of truth — All tool definitions (names, descriptions, input schemas) live in static-tools.js. The manifest, input validation, and handler dispatch all derive from this one file.

• One pattern — Every tool handler follows the same shape: validate inputs, construct the Ontraport API call, execute it, return the result. Error handling is handled by the client and transport layers.

• No abstraction without repetition — Each tool module is a flat set of exported async functions. No base classes, no middleware chains, no framework beyond Express and the MCP SDK.

Tool Reference

Contacts (7 tools)

Tags (6 tools)

Sequences & Campaigns (4 tools)

Tasks (5 tools)

Notes (2 tools)

Messages (2 tools)

Purchases & Orders (5 tools)

Transactions Write (13 tools)

These tools modify financial records. Agents should confirm with the user before executing.

Products (2 tools)

Custom Objects (4 tools per object)

These tools are dynamically generated for each custom object discovered in the account via /objects/meta. The tool names include the object's name, and the object_type_id is automatically injected.

Metadata & Discovery (2 tools)

Input Reference

Condition Parameter

The condition parameter is used across all search and list tools. It is a JSON-encoded string containing an array of criteria objects.

Single condition:

[{"field":{"field":"lastname"},"op":"=","value":{"value":"Smith"}}]

Supported operators:

Compound conditions:

Insert "AND" or "OR" strings between criteria objects:

[{"field":{"field":"lastname"},"op":"=","value":{"value":"Smith"}}, "AND", {"field":{"field":"city"},"op":"=","value":{"value":"Austin"}}]

Pagination

All list/search tools support pagination:

Timestamps

All date/time fields use Unix timestamps (seconds since January 1, 1970 00:00:00 UTC). Agents must convert human-readable dates to Unix timestamps before passing them to any tool.

List Selection Fields

Custom fields of the list selection type require option IDs wrapped with the */* delimiter:

"f1500": "*/*1*/*2*/*"

Use get_object_meta to discover option IDs for list fields.

Error Handling

The server translates Ontraport API errors into structured responses that give agents enough information to decide whether to retry, fix inputs, or report to the user.

Error response format:

{
  "code": 400,
  "error": "bad_request",
  "message": "id is required for update_contact."
}

Manifest Size Guard

If an account has many custom objects, the manifest can exceed what fits in an LLM's context window. The server enforces a maximum of 100 tools:

1. All 48 static tools are always included

2. Custom objects are sorted by most recently modified

3. Custom object tools are included in groups of 4 (one complete object at a time) until the limit is reached

4. If truncated, a _manifest_note tool is added telling the agent that additional objects exist and can be discovered via get_object_meta

Rate Limiting

The server does not add its own rate limiting. It inherits Ontraport's limit of 180 API requests per minute per account transparently. When the limit is exceeded, the server returns HTTP 429 with the Retry-After header from Ontraport so the agent can back off appropriately.

Security

• Credential passthrough — Api-Key and Api-Appid are forwarded to Ontraport on each call and never stored.

• Session credential binding — Sessions are bound to credentials via SHA-256 hash. Returning requests must present the same Api-Key/Api-Appid that created the session. Prevents session hijacking across accounts.

• Auth on all endpoints — Api-Key and Api-Appid headers are validated on every request — POST, GET (SSE), and DELETE — not just session creation.

• Per-session isolation — Each agent connection gets its own Server instance scoped to its credentials. No shared mutable state between sessions.

• Session TTL — Abandoned sessions are automatically cleaned up after 30 minutes of inactivity. A background sweep runs every 5 minutes to prevent memory leaks.

• No logging of credentials — Error handlers log only err.message, never full error objects that could contain credentials in stack traces.

• No persistence — The server has no database, no file storage. In-memory sessions track only the MCP transport lifecycle.

• Scope enforcement — Permissions are enforced by Ontraport's existing API key scope system. If a key lacks a scope, the API call fails and the server surfaces the error.

Testing

npm test

The test suite includes 106 tests across 17 suites:

Configuration

What Is Excluded from v1

The following are intentionally excluded and may be considered for future versions:

Object Type ID Reference

Custom objects have IDs assigned dynamically and are discovered via /objects/meta.