> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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

<ParamField path="config" type="Config" optional>
  Optional configuration object to customize the MCP server behavior. See [Configuration Schema](/api/configuration) for all available options.

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

<ParamField path="contextGetter" type="() => Promise<BrowserContext>" optional>
  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
</ParamField>

## 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

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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

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

### Connect to Remote Browser

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

### Connect via CDP Endpoint

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

## Related

* [Configuration Schema](/api/configuration) - Full configuration options
* [Tool Capabilities](/api/capabilities) - Available capability groups
* [Playwright BrowserContext](https://playwright.dev/docs/api/class-browsercontext) - Playwright's BrowserContext API