createConnection

Create an MCP server instance with Playwright browser automation

The createConnection function is the main entry point for creating a Playwright MCP server instance programmatically.

Function Signature

import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
import type { Config } from './config';
import type { BrowserContext } from 'playwright';

export declare function createConnection(
  config?: Config,
  contextGetter?: () => Promise<BrowserContext>
): Promise<Server>;

Parameters

config · Config

Optional configuration object to customize the MCP server behavior. See Configuration Schema for all available options.

If not provided, defaults will be used (persistent profile, chromium browser, all core capabilities enabled).

contextGetter · () => Promise<BrowserContext>

Optional function that returns a Playwright BrowserContext. This allows you to provide your own browser context instead of letting the server create one.

Useful for:

• Using an existing authenticated browser session
• Sharing a browser context across multiple connections
• Custom context initialization logic

Return Value

Returns a Promise<Server> that resolves to an MCP Server instance from @modelcontextprotocol/sdk.

The server instance can be connected to various transports:

• SSE (Server-Sent Events) for HTTP-based communication
• stdio for command-line based communication
• Custom transports

Basic Example

import { createConnection } from '@playwright/mcp';

// Create with default configuration
const server = await createConnection();

// Create with custom configuration
const server = await createConnection({
  browser: {
    browserName: 'chromium',
    launchOptions: { headless: true }
  },
  capabilities: ['core', 'pdf', 'vision'],
  timeouts: {
    action: 10000,
    navigation: 30000
  }
});

HTTP Server Integration

Integrate with an HTTP server using SSE transport:

import http from 'http';
import { createConnection } from '@playwright/mcp';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';

http.createServer(async (req, res) => {
  // Creates a headless Playwright MCP server with SSE transport
  const connection = await createConnection({
    browser: { launchOptions: { headless: true } }
  });
  const transport = new SSEServerTransport('/messages', res);
  await connection.connect(transport);
}).listen(8931);

Custom Browser Context

Provide your own browser context for advanced control:

import { createConnection } from '@playwright/mcp';
import { chromium } from 'playwright';

// Create your own browser and context
const browser = await chromium.launch({ headless: false });
const context = await browser.newContext({
  viewport: { width: 1920, height: 1080 },
  userAgent: 'Custom User Agent'
});

// Provide context to createConnection
const server = await createConnection(
  { /* config options */ },
  async () => context
);

Configuration Examples

Headless with Specific Capabilities

const server = await createConnection({
  browser: {
    launchOptions: { headless: true }
  },
  capabilities: ['core', 'pdf', 'vision'],
  outputMode: 'file',
  outputDir: './playwright-output'
});

Connect to Remote Browser

const server = await createConnection({
  browser: {
    remoteEndpoint: 'ws://remote-browser:9222'
  }
});

Connect via CDP Endpoint

const server = await createConnection({
  browser: {
    cdpEndpoint: 'http://localhost:9222',
    cdpTimeout: 60000
  }
});

Related

• Configuration Schema - Full configuration options
• Tool Capabilities - Available capability groups
• Playwright BrowserContext - Playwright’s BrowserContext API