@zapier/mcp-integration

@zapier/mcp-integration

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

Table of Contents

• 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.

License

MIT © Zapier