@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
• Quick Start
• Setup
• MCP Actions
• API Actions
• Configuration
• API Reference
• TypeScript Support
• Examples

Installation

Install the package via npm:

npm install @zapier/mcp-integration

Prerequisites

• Activate the Gargoyle switch zcache via https://admin.zapier.com/nexus/gargoyle/ for the CLI App: app_id found in your .zapierapprc file after running zapier register.

Quick Start

Here's a minimal example to get started:

Create a file called mcp.ts:

export const mcp = new Proxy({
  name: packageJson.name,
  version: packageJson.version,
  serverUrl: process.env.SERVER_URL,
  transport: 'sse', // or 'streamable'
});

Use it to initialize your app in index.ts:

import { Proxy } from '@zapier/mcp-integration';
import packageJson from '../package.json' with { type: 'json' };
import { mcp } from './mcp.js';

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

  triggers: {
    my_trigger: {
      noun: 'Item',
      display: {
        label: 'New Item',
        description: 'Triggers when a new item is available.',
      },
      operation: {
        perform: async (z, bundle) => {
          // Call MCP tool
          return await mcp.callTool({
            name: 'list_items',
            arguments: {},
          });
        },
      },
    },
  },
});

Make sure your tsconfig.json includes .json files:

{
  // other options
  "include": ["src/**/*", "src/*.json"]
}

NOTE: Just src/**/* will only include supported extensions (.ts etc)

Make sure your .zapierapprc includes the .json files:

{
  // other options
  "includeInBuild": ["dist/.*.json"]
}

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.defineApp(),

  // .. (your actions)
});

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.defineApp({ 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.defineApp 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',
    token: 'your-bearer-token',
  },
});

Transport Options

Choose between two transport protocols:

• sse (Server-Sent Events) - Recommended for most use cases
• streamable (HTTP streaming) - Alternative transport option

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: 'sse' | 'streamable' - Transport protocol
• auth?: AuthConfig - Authentication configuration (optional)

AuthConfig:

OAuth configuration:

{
  type: 'oauth';
  clientInformation: OAuthClientInformationFull;
  tokens: OAuthTokens;
}

Bearer token configuration:

{
  type: 'bearer';
  token: string;
}

Methods

defineApp(options?: AppOptions): App

Returns Zapier app configuration with MCP integration.

AppOptions:

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

Returns: Zapier App configuration including middleware and lifecycle hooks.

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 (optional)

Returns: Promise that resolves to the tool's response, optionally filtered and parsed.

Throws: Error when the tool call fails and error is true.

defineBeforeRequest(): BeforeRequestMiddleware

Returns middleware for handling authentication in API requests.

Returns: Middleware function that injects Bearer tokens into request headers.

listTools(params?: { cursor?: string }): Promise<{ tools: Tool[]; cursor: string }>

Lists available MCP tools with pagination support.

listAllTools(): Promise<Tool[]>

Lists all available MCP tools by automatically handling pagination.

getTool(name: string): Promise<Tool | undefined>

Retrieves a specific MCP tool by name.

getServerVersion(): Promise<ServerVersion>

Gets the MCP server version and metadata.

OAuth Methods

• authorizeUrl(z: ZObject, bundle: Bundle): Promise<string> - Gets OAuth authorization URL
• getAccessToken(z: ZObject, bundle: Bundle): Promise<GetAccessTokenResult> - Exchanges code for tokens
• refreshAccessToken(z: ZObject, bundle: Bundle): Promise<{}> - Refreshes expired tokens

Utility Methods

• defineTest(): Function - Connection test function for Zapier
• defineConnectionLabel(): Function - Connection label generator
• close(): Promise<void> - Closes the MCP client connection
• configure(config: Partial<Config>): void - Updates proxy configuration
• getConnectedClient(): Promise<Client> - Gets connected MCP client
• generateActions(): Promise<unknown> - Generates actions from MCP tools
• defineActions(transformer?: ActionsTransformer): Promise<Actions> - Defines actions from generated JSON

Utility Functions

convertInputSchemaToFields(schema: Tool['inputSchema']): PlainInputField[]

Converts MCP tool input schemas to Zapier input field format.

Parameters:

• schema: Tool['inputSchema'] - The MCP tool's input schema

Returns: Array of Zapier PlainInputField objects for form generation.

TypeScript Support

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

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

const mcp = new Proxy({
  name: 'my-integration',
  version: '1.0.0',
  serverUrl: process.env.SERVER_URL!,
  transport: 'sse',
});

// Convert MCP tool schema to Zapier fields
const zapierFields = convertInputSchemaToFields(tool.inputSchema);

The package provides comprehensive TypeScript support with internal type definitions. All necessary typing is handled automatically when using the exported classes and functions.

Examples

Basic Tool Call

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

const mcp = new Proxy({
  name: 'weather-integration',
  version: '1.0.0',
  serverUrl: 'https://weather-mcp-server.com',
  transport: 'sse',
});

// Call a weather tool
const weather = await mcp.callTool({
  name: 'get_weather',
  arguments: {
    location: 'San Francisco',
    units: 'metric',
  },
});

console.log(weather);

With JSONata Filtering

// Get only temperature from weather data
const temperature = await mcp.callTool({
  name: 'get_weather',
  arguments: { location: 'San Francisco' },
  filter: 'content[0].json.temperature',
});

OAuth Integration

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

const mcp = new Proxy({
  name: 'my-oauth-integration',
  version: '1.0.0',
  serverUrl: process.env.SERVER_URL,
  transport: 'sse',
});

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

  authentication: {
    type: 'oauth2',
    oauth2Config: {
      authorizeUrl: mcp.authorizeUrl.bind(mcp),
      getAccessToken: mcp.getAccessToken.bind(mcp),
      refreshAccessToken: mcp.refreshAccessToken.bind(mcp),
    },
    test: mcp.defineTest(),
    connectionLabel: mcp.defineConnectionLabel(),
  },
});

Converting Tool Schema to Zapier Fields

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

// Get a tool and convert its schema
const tool = await mcp.getTool('my_tool');
if (tool) {
  const zapierFields = convertInputSchemaToFields(tool.inputSchema);

  // Use zapierFields in your action's inputFields
  const myAction = {
    // ...other config
    operation: {
      inputFields: zapierFields,
      perform: async (z, bundle) => {
        return await mcp.callTool({
          name: 'my_tool',
          arguments: bundle.inputData,
        });
      },
    },
  };
}

Contributing

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

License

MIT © Zapier