@zapier/mcp-integration

SDK for integrating with Model Context Protocol (MCP) servers, designed for use in Zapier integrations.

Installation
Migration Guide
Setup
MCP Actions
API Actions
Configuration
API Reference
TypeScript Support

Installation

Install the package via npm:

npm install @zapier/mcp-integration

Migration Guide

If you're migrating from the embedded MCP SDK in mcp-client-integration, this package is a drop-in replacement. Simply update your import statement:

Before:

import { Proxy } from '../sdk/index.js';

After:

import { Proxy } from '@zapier/mcp-integration';

All other code remains unchanged. The API is identical, and all functionality is preserved.

Setup

You can use @zapier/mcp-integration in two ways:

As Foundation

In this mode, you use @zapier/mcp-integration to handle authentication and all or most actions.

Create e.g. src/mcp.ts with the following content:

import { Proxy } from '@zapier/mcp-integration';

import packageJson from '../package.json' with { type: 'json' };

export const mcp = new Proxy({
  name: packageJson.name,
  version: packageJson.version,
  serverUrl: process.env.SERVER_URL,
  transport: process.env.TRANSPORT,
});

Update src/index.ts to use the singleton:

import { mcp } from './mcp.js';

export default defineApp({
  ...mcp.app(),

  // .. (your actions)

  // If you need additional `beforeRequest` middleware:
  // beforeRequest: [mcp.beforeRequest(), yourMiddleware],
});

For Actions only

In this mode, you handle authentication yourself, and use @zapier/mcp-integration for some of the actions.

Create e.g. src/mcp.ts with the following content:

import { Proxy } from '@zapier/mcp-integration';

import packageJson from '../package.json' with { type: 'json' };

export const mcp = new Proxy({
  name: packageJson.name,
  version: packageJson.version,
  serverUrl: process.env.SERVER_URL,
  transport: process.env.TRANSPORT,
  auth: {
    type: 'oauth',
  },
});

Update src/index.ts to use the singleton:

import { mcp } from './mcp.js';

export default defineApp({
  ...mcp.app({ handleAuth: false }),

  authentication: yourAuthConfig,

  // .. (your actions)
});

MCP Actions

Use the singleton to call a tool:

import { mcp } from './mcp.js';

const perform = async (z: ZObject, bundle: Bundle) => {
  const result = await mcp.callTool({
    name: 'my_tool',
    arguments: {
      hello: 'world',
    },
    // Override these default options as needed:
    // parse: true,
    // error: true,
    // filter: "content[0].json",
  });

  return result;
};

// Action configuration, leveraging perform

API Actions

Use z.request() as normally, as unless you have called mcp.app with { handleAuth: false }, it will have injected beforeRequest middleware to inject tokens into requests.

Configuration

Authentication Options

The Proxy class supports multiple authentication methods:

OAuth 2.0 Authentication

import { Proxy } from '@zapier/mcp-integration';

const mcp = new Proxy({
  name: 'my-integration',
  version: '1.0.0',
  serverUrl: process.env.SERVER_URL,
  transport: process.env.TRANSPORT,
  auth: {
    type: 'oauth',
    // OAuth configuration handled automatically
  },
});

Bearer Token Authentication

import { Proxy } from '@zapier/mcp-integration';

const mcp = new Proxy({
  name: 'my-integration',
  version: '1.0.0',
  serverUrl: process.env.SERVER_URL,
  transport: process.env.TRANSPORT,
  auth: {
    type: 'bearer',
    // Bearer token configuration handled automatically
  },
});

Tool Call Configuration

Configure how MCP tools are called:

const result = await mcp.callTool({
  name: 'my_tool',
  arguments: { param: 'value' },
  parse: true, // Parse JSON responses (default: true)
  error: true, // Throw on MCP errors (default: true)
  filter: 'data.items', // JSONata filter expression (optional)
});

API Reference

Proxy Class

The main class for interacting with MCP servers.

Constructor

new Proxy(config: ProxyConfig)

ProxyConfig:

name: string - Integration name
version: string - Integration version
serverUrl: string - MCP server URL
transport: string - Transport protocol
auth?: AuthConfig - Authentication configuration

Methods

`app(options?: AppOptions): Partial<App>`

Returns Zapier app configuration with MCP integration.

AppOptions:

handleAuth?: boolean - Whether to handle authentication (default: true)

`callTool(options: CallToolOptions): Promise<any>`

Calls an MCP tool with the specified arguments.

CallToolOptions:

name: string - Tool name
arguments: Record<string, any> - Tool arguments
parse?: boolean - Parse JSON responses (default: true)
error?: boolean - Throw on errors (default: true)
filter?: string - JSONata filter expression

`beforeRequest(): BeforeRequestMiddleware`

Returns middleware for handling authentication in API requests.

Authentication Providers

BearerTokenAuthProvider

Handles Bearer token authentication for API requests.

OAuthClientProvider

Handles OAuth 2.0 authentication flow and token management.

Utility Functions

`convertInputSchemaToFields(schema: any): PlainInputField[]`

Converts MCP tool input schemas to Zapier input field format.

`isTextContentItem(item: any): boolean`

Type guard to check if content item is text-based.

TypeScript Support

This package is written in TypeScript and includes comprehensive type definitions. All types are automatically available when using TypeScript:

import {
  Proxy,
  type ProxyConfig,
  type CallToolOptions,
} from '@zapier/mcp-integration';

const config: ProxyConfig = {
  name: 'my-integration',
  version: '1.0.0',
  serverUrl: process.env.SERVER_URL!,
  transport: process.env.TRANSPORT!,
};

const mcp = new Proxy(config);

Available Types

ProxyConfig - Configuration for Proxy constructor
CallToolOptions - Options for calling MCP tools
AuthConfig - Authentication configuration
BeforeRequestMiddleware - Middleware function type
Bundle - Zapier bundle type (internalized)
ZObject - Zapier z object type (internalized)
App - Zapier app configuration type (internalized)
PlainInputField - Zapier input field type (internalized)

Contributing

This package is part of the Zapier MCP integration project. For issues and contributions, please visit the GitLab repository.