MCP Server

SeamScape exposes a Model Context Protocol server for authenticated pattern automation. Use it from MCP-capable clients to discover pattern assets, open headless pattern sessions, inspect elements, preview edits, apply confirmed Pattern API commands, save versions, and export generated artwork.

The server uses the same account and organisation access rules as the SeamScape API. The bearer token identifies the user. API clients can send a SeamScape API key; ChatGPT apps use OAuth 2.1 and receive a SeamScape access token after the user signs in. Organisation access follows that user's active organisation unless the request includes X-SeamScape-Organization-Id.

Each user has one active Pattern Studio/MCP session. Most pattern_api_* tools can omit sessionId; when omitted, the active session is used.

Endpoint

/api/mcp

Transport: MCP Streamable HTTP
Methods: GET, POST, and DELETE
Authentication: Required. Send Authorization: Bearer <TOKEN>. SeamScape API keys and SeamScape OAuth access tokens are supported.
Organisation override: Optional. Send X-SeamScape-Organization-Id: <ORGANIZATION_ID> to use a specific organisation that your user belongs to, or X-SeamScape-Organization-Id: personal for no organisation context.

Manage your personal API key in Account > API Keys. ChatGPT obtains OAuth tokens automatically through the SeamScape authorization flow.

Client Examples

MCP clients use different configuration formats, but the required values are the same: the Streamable HTTP endpoint URL and an Authorization bearer token. API-key clients supply the token directly; ChatGPT discovers the OAuth metadata and completes the login flow for the user. Add X-SeamScape-Organization-Id only when you want to override your active organisation.

Generic MCP client

{
  "mcpServers": {
    "seamscape": {
      "type": "streamable-http",
      "url": "https://seamscape.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "X-SeamScape-Organization-Id": "ORGANIZATION_ID"
      }
    }
  }
}

Codex

Codex reads MCP servers from ~/.codex/config.toml. Prefer an environment variable for the SeamScape API key.

export SEAMSCAPE_API_KEY="YOUR_API_KEY"

codex mcp add seamscape \
  --url https://seamscape.com/api/mcp \
  --bearer-token-env-var SEAMSCAPE_API_KEY

Equivalent config:

[mcp_servers.seamscape]
url = "https://seamscape.com/api/mcp"
bearer_token_env_var = "SEAMSCAPE_API_KEY"

Claude Code

Claude Code can add a remote HTTP MCP server and send a bearer token header.

export SEAMSCAPE_API_KEY="YOUR_API_KEY"

claude mcp add --transport http seamscape https://seamscape.com/api/mcp \
  --header "Authorization: Bearer $SEAMSCAPE_API_KEY"

For shared project configuration, use environment variable expansion in .mcp.json:

{
  "mcpServers": {
    "seamscape": {
      "type": "http",
      "url": "https://seamscape.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${SEAMSCAPE_API_KEY}"
      }
    }
  }
}

ChatGPT Developer Mode

ChatGPT Developer Mode connects remote MCP servers from the ChatGPT Apps settings. Use these values when creating the app:

Name	SeamScape
MCP server URL	`https://seamscape.com/api/mcp`
Protocol	Streaming HTTP
Authentication	OAuth 2.1 authorization code with PKCE

SeamScape exposes protected-resource metadata at /.well-known/oauth-protected-resource and authorization-server metadata at /.well-known/oauth-authorization-server. ChatGPT registers a dynamic OAuth client, sends the user to /oauth/authorize, then calls /oauth/token and uses the returned bearer token for MCP requests.

OpenAI Responses API

If you are building your own OpenAI API integration, pass the SeamScape API key as the MCP authorization value for each response request.

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.5",
  tools: [
    {
      type: "mcp",
      server_label: "seamscape",
      server_description: "SeamScape pattern automation tools.",
      server_url: "https://seamscape.com/api/mcp",
      authorization: process.env.SEAMSCAPE_API_KEY
    }
  ],
  input: "List my available SeamScape patterns."
});

console.log(response.output_text);

Store API keys in your client or deployment secret store. Do not commit them to source control.

Safe Edit Flow

Use pattern_library_list_patterns and pattern_library_list_versions to find a target.
Use load_pattern, load_pattern_version, or create_empty_pattern_session to create a session.
Alternatively, enable the MCP session in Pattern Studio and use get_active_pattern_session.
Inspect the session with pattern_api_summary, pattern_api_find_elements, or pattern_api_get_element.
Use pattern_api_get_command_schema before constructing a command payload.
Run pattern_api_preview_command first. Preview never commits changes.
Run pattern_api_apply_command with confirm: true only after reviewing the preview.
Run pattern_api_save_session with confirm: true only when the session should be written to persistent storage.

Applying a command mutates the in-memory MCP session and persists temporary session state. It does not save a Pattern or PatternVersion until pattern_api_save_session succeeds.

Tools

Pattern library

Tool	Description
`pattern_library_list_patterns`	List accessible patterns without loading full pattern JSON.
`pattern_library_list_versions`	List available versions for one accessible pattern.

Sessions

Tool	Description
`create_empty_pattern_session`	Create a new unsaved headless pattern session.
`load_pattern`	Load the current/default version of a pattern into a session.
`load_pattern_version`	Load a specific pattern version by version ID or version number.
`list_pattern_sessions`	List sessions for the authenticated user and mark the active one.
`get_active_pattern_session`	Return the authenticated user's active Pattern Studio/MCP session.

Inspection

Tool	Description
`list_pattern_api_tools`	List available read-only Pattern API tools.
`pattern_api_summary`	Return a compact summary of a session.
`pattern_api_find_elements`	Find pattern elements by kind, text, and selection state.
`pattern_api_get_element`	Inspect one element by ID.
`pattern_api_inspect_constraints`	Inspect boundary and nearby construction constraints around a piece or element.
`pattern_api_inspect_pieces`	Inspect actual pattern pieces and boundary-driving draft points.
`pattern_api_validate_piece_shapes`	Validate computed piece cut boundaries.
`pattern_api_errors`	Return current constraint and formula errors.

Commands

Tool	Description
`pattern_api_list_commands`	List available serializable Pattern API commands.
`pattern_api_describe_command`	Describe one command contract.
`pattern_api_get_command_schema`	Return a serializable input schema for one command.
`pattern_api_preview_command`	Dry-run a command without committing changes.
`pattern_api_apply_command`	Apply a command to the in-memory session when confirm is true.

Persistence and export

Tool	Description
`pattern_api_save_session`	Save a session as a Pattern or PatternVersion when confirm is true.
`pattern_api_export_svg`	Render the current in-memory session as SVG.
`pattern_api_export_png`	Render the current in-memory session as PNG image content.

Example Command Payload

Command payloads are JSON objects with a type field. The exact fields depend on the command schema returned by pattern_api_get_command_schema. sessionId is optional when the authenticated user has an active session.

{
  "command": {
    "type": "pattern.setName",
    "name": "Updated pattern name"
  }
}

Use this shape with pattern_api_preview_command. To apply the same command, send the same command with confirm: true to pattern_api_apply_command. Add sessionId only when targeting a non-active session explicitly.

< SeamScape in Action API v1 Reference >