ETL: MCP Server

The Integrate.io MCP server exposes a Model Context Protocol (MCP) endpoint that AI assistants such as Claude Desktop or the MCP Inspector can call to inspect and act on your account. Assistants connect over JSON-RPC 2.0 and use a curated set of tools to list workspaces, list packages, inspect runs, search resources, validate pipelines, preview database data, and — with explicit mutating tools — clone packages, edit components, manage schedules, and run jobs. Credentials, TLS certificates, and SSL keys are never returned. Use the MCP server when you want an AI assistant to answer questions about what exists in your account, summarize pipeline state, diagnose run failures, preview source data before designing a transformation, or perform routine operations (clone a package as a template, toggle a schedule, retry a failed job) on your behalf.

The MCP server is a per-account feature gated by the ptp_mcp_server flag. Contact Integrate.io support to enable it for your account before completing the steps below.

Available tools

The server registers 22 tools, grouped by what they do. Read-only tools inspect account state without side effects. Mutating tools create, modify, or run packages and jobs — they’re flagged below.

Account inventory (read-only)

Tool	Description
`list_workspaces`	Lists workspaces in the account with `package_count`, `last_failed_jobs_count`, and `last_completed_jobs_count`. Recommended starting point for AI assistants.
`list_packages`	Lists packages (ETL pipeline definitions). Filterable by `flow_type` (`dataflow` or `workflow`), `status` (`active` or `archived`), and `workspace_id`. Includes `last_run_status`.
`get_package`	Returns a single package by `package_id` with a curated data flow graph summary (component count, edge count, component-type tally, variables count). Set `include_full_graph: true` to return the full `data_flow_json` blob.
`list_connections`	Lists database and cloud-storage connections. Returns `id`, `name`, `type`, and `status` only. Optional `connection_type_filter`.
`get_connection`	Returns details for a single connection by `connection_id`. Includes non-credential identifying fields such as `host`, `port`, `database`, and `tunnel_type`.
`list_clusters`	Lists compute clusters with `status`, `type`, `nodes`, `region`, lifecycle timestamps, and `terminate_on_idle`. Filter by `status`.
`search_all`	Free-text search across connections, packages, clusters, and workspaces, backed by Elasticsearch. Narrow with `types` and cap per-type hits with `per_type_limit` (default 10, max 50).

Run inspection (read-only)

Tool	Description
`list_runs`	Lists recent job runs with `status`, `started_at`, `completed_at`, `runtime_in_seconds`, `cluster_id`, `package_id`, and `last_error` for failed runs. Filter by `package_id` or `status`. Excludes child retries by default.
`get_run`	Returns a single run by `run_id` plus a redacted log tail. Use `log_tail_lines` to control how many trailing lines to return (default 20, max 200).
`explain_job_failure`	Returns the run’s primary error, a redacted log tail, programmatic error-pattern detection (FATAL, ERROR, exception, auth, connection, schema), and heuristic next-step suggestions. Use `log_tail_lines` to control tail size (default 50, max 200).

Schedule inspection (read-only)

Tool	Description
`list_schedules`	Lists schedules in the account with `name`, `package_id`, `cron`, `next_run_at`, and `enabled`. Filter by `package_id` or `enabled`.
`get_schedule`	Returns one schedule by `schedule_id` with its full cron expression, variables, and timing metadata.

Pipeline diagnostics (read-only)

Tool	Description
`validate_package`	Runs the same synchronous validation the web UI does: structural check plus a JMS script validation. Returns a per-component error list. Each call creates a `JobValidation` record and typically takes ~5 seconds.
`discover_schema`	Lists tables available through a database connection. Optional `schema_name`, `limit`, `offset`, and `search` arguments. Only works for database connection types.
`preview_data`	Returns column metadata plus a small sample of rows from a database table. Optional `schema_name`, `row_count` (default 20, max 200), and `where_clause` (single fragment; semicolons and SQL comment markers are rejected).
`test_connection`	Actively pings a connection’s upstream system. Returns `success: true/false` with an `error_message` on failure. Optional `connection_type` disambiguates when the same id exists in both the database and cloud-storage connection tables.

Pipeline mutations (write — agent edits the package itself)

Tool	Description
`clone_package`	Duplicates an existing package by `package_id` into a new package with optional `name` and `workspace_id` overrides. Returns the new `package_id`.
`update_package_components`	Edits specific components within a package’s `data_flow_json`. Each entry is `{ component_name, updates }`; nested hashes are deep-merged. All-or-nothing semantics: if any `component_name` isn’t found, no writes happen. Bumps the package version via PaperTrail; reversible via the existing UI history.

Schedule mutations (write)

Tool	Description
`toggle_schedule`	Enables or disables a schedule by `schedule_id`. Set `enabled: true` or `enabled: false`.

Execution + recovery (write)

Tool	Description
`run_package`	Submits a package for execution and returns the `run_id` immediately (doesn’t wait for completion). Poll status via `get_run`. Optional `cluster_id`, `variables`, and `dynamic_variables`.
`cancel_job`	Cancels a currently-running job by `run_id`. Idempotent — calling on an already-finished job returns the current status without erroring.
`retry_job`	Retries a failed job by `run_id`, optionally on a different `cluster_id`. Creates a new run; the original run is preserved for history.

All tools are scoped to the authenticated account. None return credentials or other sensitive material. Tools that hit external services (validate_package, discover_schema, preview_data, test_connection, run_package) cause real network calls to JMS, the schema-importer, or your upstream systems. Use them sparingly.

Endpoint

POST /:account_id/api/mcp

The endpoint accepts a single JSON-RPC 2.0 message per request. Batch requests are not supported. Authentication uses a bearer token in the Authorization header. The token must belong to a user with access to the account named in the URL. Cross-account requests return 403 Forbidden.

Prerequisites

The ptp_mcp_server feature flag enabled for your account.
A bearer token for a user with access to the account. The recommended way to get one is Connected Applications in the dashboard (see Step 1).
An MCP-capable client. The setup below covers Claude Desktop 0.7.0 or later and the MCP Inspector.

Step 1: Get a Personal Access Token

The simplest way to get a token is from the Connected Applications page in your Integrate.io dashboard — no curl, no password grant, no token expiry to manage.

Sign in to your dashboard and navigate to Settings → Developer Settings → Connected Applications. (Direct URL: https://dashboard.xplenty.com/<your-account>/settings/developer/connected_applications)
Click + Create new connection.
Give it a recognizable name (e.g. “Claude Desktop on Macbook”) and click Create token.
The token is displayed once in a reveal modal. Click Copy before closing the modal — Integrate.io does not store the plaintext token and cannot show it again. If you lose it, revoke the connection and create a new one.

The reveal modal also includes ready-to-paste configuration snippets for Claude Desktop, Claude Code, the MCP Inspector, and curl. You can skip ahead to Step 3 and paste the Claude Desktop snippet directly into your config file.

Why Connected Applications instead of an OAuth grant request?Connected Applications mint long-lived Personal Access Tokens (PATs) tied to a specific named integration. You don’t need to keep re-running an OAuth password-grant call every two hours, and you can revoke a token from the same page without affecting your dashboard session. Each connection appears in the list with its name, scope, and creation date — making it easy to audit which agent is connected to your account.A connection can be revoked at any time from the same page — the bearer immediately stops working everywhere it’s pasted.

Alternative: OAuth password grant (legacy)

If you can’t use Connected Applications (e.g., automation that must mint tokens programmatically without a logged-in user), you can still use the OAuth Resource Owner Password Credentials grant. These tokens expire after two hours, so you’ll need to refresh them regularly.

curl -X POST 'https://api.xplenty.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "email": "you@your-org.com",
    "password": "your-password"
  }'

The response includes the access_token:

{
  "access_token": "ABC123...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "created_at": 1234567890
}

For interactive use with Claude Desktop or MCP Inspector, prefer Connected Applications — the 10-year PAT lifetime means you set it up once and forget it.

Step 2: Configure your MCP client

Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add an entry under mcpServers. Claude Desktop speaks MCP over stdio only, so the snippet uses mcp-remote as a thin bridge to the remote HTTP endpoint:

{
  "mcpServers": {
    "integrateio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

Replace YOUR_ACCOUNT_ID with your account subdomain or numeric id and YOUR_ACCESS_TOKEN with the value from Step 1, then restart Claude Desktop (Cmd+Q on macOS — fully quit and reopen; reloading the window isn’t enough).

The Connected Applications reveal modal generates this snippet for you with the URL and token already filled in. Click Copy under the Claude Desktop tab, paste into your config, restart Claude.

Claude Code

Claude Code has native HTTP MCP support — no bridge needed. Run:

claude mcp add --transport http integrateio \
  https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

MCP Inspector

The MCP Inspector has a native UI for ad-hoc debugging. Launch it:

npx @modelcontextprotocol/inspector

Then in the UI:

Transport: Streamable HTTP
URL: https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp
Headers: Authorization: Bearer YOUR_ACCESS_TOKEN

The Inspector lets you call tools/list and tools/call directly and view the JSON-RPC response.

Cursor

Cursor uses the same stdio-only MCP transport as Claude Desktop. Use the same mcp-remote bridge — edit ~/.cursor/mcp.json (or per-workspace .cursor/mcp.json) with the JSON snippet above.

Other MCP clients

Anything that supports the Streamable HTTP MCP transport natively can hit https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp directly with an Authorization: Bearer <token> header — no bridge needed. Stdio-only clients need mcp-remote (or an equivalent stdio↔HTTP bridge) to talk to the endpoint.

Step 3: Verify the connection

In Claude Desktop, type /mcp in the chat input. You should see integrateio listed with all 22 tools available. Try a prompt such as:

List the workspaces in my Integrate.io account.

Claude invokes tools/call with list_workspaces and returns the response payload.

Example: Calling a tool with curl

You can also call the endpoint directly. The body is a JSON-RPC 2.0 request.

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_packages",
      "arguments": { "status": "active", "limit": 10 }
    }
  }'

To diagnose a failed run, call explain_job_failure with the run id:

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "explain_job_failure",
      "arguments": { "run_id": 123456, "log_tail_lines": 100 }
    }
  }'

To preview source data before designing a transformation:

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "preview_data",
      "arguments": {
        "connection_id": 42,
        "table": "orders",
        "row_count": 20,
        "where_clause": "amount > 1000"
      }
    }
  }'

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	Missing or expired token	Mint a new token in Step 1. If you’re using an OAuth password-grant token, remember those expire after 2 hours — switch to a Connected Application PAT for a long-lived token.
`401 Unauthorized` after revoking a Connected Application	The connection was deleted from Settings → Developer Settings → Connected Applications	Create a new connection from that page and update your client config. Revocation takes effect immediately.
`403 PTP MCP server is not enabled for this account`	Feature flag is off	Contact Integrate.io support to enable `ptp_mcp_server`.
`403 Forbidden`	Token belongs to a user without access to the account in the URL	Use a token for a user who is a member of the target account.
`404 Not Found`	Wrong account id in URL	Use the account id or subdomain from your Integrate.io dashboard URL.
`{"error":{"code":-32600,...}}`	Malformed JSON-RPC body	Verify the request body matches the JSON-RPC 2.0 shape.
`{"error":"connection not found, or not a database connection"}`	Called `discover_schema` or `preview_data` against a cloud-storage or SaaS connection	These tools support database connections only. Use `get_connection` to confirm the type.

Getting Started

Packages & Workflows

Sources

Transformations

Expressions & Functions

Destinations

Scheduling, Jobs & Clusters

Alerts & Monitoring

Security & Access

Account Management

Available tools

Account inventory (read-only)

Run inspection (read-only)

Schedule inspection (read-only)

Pipeline diagnostics (read-only)

Pipeline mutations (write — agent edits the package itself)

Schedule mutations (write)

Execution + recovery (write)

Endpoint

Prerequisites

Step 1: Get a Personal Access Token

Alternative: OAuth password grant (legacy)

Step 2: Configure your MCP client

Claude Desktop

Claude Code

MCP Inspector

Cursor

Other MCP clients

Step 3: Verify the connection

Example: Calling a tool with curl

Troubleshooting

Getting Started

Packages & Workflows

Sources

Transformations

Expressions & Functions

Destinations

Scheduling, Jobs & Clusters

Alerts & Monitoring

Security & Access

Account Management

Documentation Index

​Available tools

​Account inventory (read-only)

​Run inspection (read-only)

​Schedule inspection (read-only)

​Pipeline diagnostics (read-only)

​Pipeline mutations (write — agent edits the package itself)

​Schedule mutations (write)

​Execution + recovery (write)

​Endpoint

​Prerequisites

​Step 1: Get a Personal Access Token

​Alternative: OAuth password grant (legacy)

​Step 2: Configure your MCP client

​Claude Desktop

​Claude Code

​MCP Inspector

​Cursor

​Other MCP clients

​Step 3: Verify the connection

​Example: Calling a tool with curl

​Troubleshooting

Available tools

Account inventory (read-only)

Run inspection (read-only)

Schedule inspection (read-only)

Pipeline diagnostics (read-only)

Pipeline mutations (write — agent edits the package itself)

Schedule mutations (write)

Execution + recovery (write)

Endpoint

Prerequisites

Step 1: Get a Personal Access Token

Alternative: OAuth password grant (legacy)

Step 2: Configure your MCP client

Claude Desktop

Claude Code

MCP Inspector

Cursor

Other MCP clients

Step 3: Verify the connection

Example: Calling a tool with curl

Troubleshooting