MCP Integration

Firma provides two MCP servers that let AI assistants work with Firma in different ways:

Data MCP (https://mcp.firma.dev/mcp) - Gives AI assistants direct access to the Firma API. Manage templates, create signing requests, configure workspaces, and more through natural language conversations. Requires OAuth authentication.
Docs MCP (https://docs.firma.dev/mcp) - Gives AI assistants access to Firma’s full documentation and API reference. Use it to generate accurate integration code with correct endpoints, request shapes, and auth patterns. No authentication required.

Most developers want both connected: the Data MCP for operating on Firma data, and the Docs MCP for building Firma integrations.

What is MCP?

The Model Context Protocol (MCP) is an open standard that connects AI assistants to external tools and data sources. Instead of writing API calls manually, you describe what you need in plain language, and the AI assistant uses Firma’s MCP servers to execute the right API calls or look up the right documentation on your behalf.

Setup

Data MCP
Docs MCP

The Data MCP server authenticates via OAuth 2.1 with PKCE using your Firma account credentials. When you connect through any supported client, the OAuth flow is handled automatically.Supported clients:

Claude - Claude Code, Claude Desktop, Claude.ai
ChatGPT - Via Developer Mode connectors
Cursor - Native MCP support
GitHub Copilot - VS Code 1.101+
OpenAI Codex - Via CLI or config
Other MCP clients - Any client implementing the Streamable HTTP transport

Add the Firma Data MCP server via the CLI:

claude mcp add --transport http firma-api https://mcp.firma.dev/mcp

Or add it to your Claude Code configuration (.claude/settings.json):

{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}

You’ll be prompted to sign in with your Firma account on first use.

Add the server to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "firma-api": {
      "type": "url",
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}

Restart Claude Desktop after saving. You’ll be prompted to sign in with your Firma account on first use.

Add Firma to Claude.ai

Open Claude.ai Connector Settings

Click Add Connector
Enter the server URL: https://mcp.firma.dev/mcp
Complete the OAuth sign-in flow when prompted
The connector will appear in your conversation toolbar

Requires a ChatGPT Pro, Team, Enterprise, or Edu plan with Developer Mode enabled.

Add Firma to ChatGPT

Open ChatGPT Connector Settings

Click Create to add a new connector
Enter the server URL: https://mcp.firma.dev/mcp
Complete the OAuth sign-in flow when prompted
The Firma tools will appear in your conversations

Install in Cursor

One-click install for Cursor IDE

Or add manually to your project-level config (.cursor/mcp.json) or global Cursor settings:

{
  "mcpServers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}

You’ll be prompted to sign in with your Firma account on first use.

Requires VS Code 1.101+ with GitHub Copilot enabled.

Install in VS Code

One-click install for VS Code with GitHub Copilot

Or add manually to your workspace config (.vscode/mcp.json):

{
  "servers": {
    "firma-api": {
      "url": "https://mcp.firma.dev/mcp"
    }
  }
}

You’ll be prompted to sign in with your Firma account on first use.

Add the server via the Codex CLI:

codex mcp add firma-api --type url --url https://mcp.firma.dev/mcp

Or add it to your config.toml:

[mcp.firma-api]
type = "url"
url = "https://mcp.firma.dev/mcp"

You’ll be prompted to sign in with your Firma account on first use.

The Docs MCP server provides read-only access to Firma’s documentation. No authentication is required. Use it when you want your AI assistant to generate accurate Firma integration code with correct endpoint URLs, request shapes, and auth patterns.Supported clients: Any client that supports the Data MCP server also supports the Docs MCP server. The setup is the same, just with a different URL.

claude mcp add --transport http firma-docs https://docs.firma.dev/mcp

Or add it to .claude/settings.json:

{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "firma-docs": {
      "type": "url",
      "url": "https://docs.firma.dev/mcp"
    }
  }
}

Restart Claude Desktop after saving.

Add Firma Docs to Claude.ai

Open Claude.ai Connector Settings

Click Add Connector
Enter the server URL: https://docs.firma.dev/mcp
No authentication required

Add Firma Docs to ChatGPT

Open ChatGPT Connector Settings

Click Create to add a new connector
Enter the server URL: https://docs.firma.dev/mcp
No authentication required

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "firma-docs": {
      "url": "https://docs.firma.dev/mcp"
    }
  }
}

codex mcp add firma-docs --type url --url https://docs.firma.dev/mcp

Or add to config.toml:

[mcp.firma-docs]
type = "url"
url = "https://docs.firma.dev/mcp"

What the Docs MCP provides

The Docs MCP server gives AI assistants access to:

API reference - Endpoint URLs, request/response shapes, authentication details
Integration guides - Step-by-step instructions for each supported platform
Feature guides - Webhooks, embedded signing, white labeling, email templates, and more
Code examples - Working examples in Node.js, Python, and other languages

When to use it

Reference “the Firma docs” in your prompts to tell the assistant to query this server:

Using the Firma docs, create an Express route that sends a signing request
using the create-and-send endpoint. Use process.env.FIRMA_API_KEY for auth.

Without this reference, your assistant may fall back to general knowledge and miss endpoint or auth details.

Data MCP: Available tools

Once connected, the AI assistant can use the following tools. There are 84 tools organized across 10 categories.

The core workflow tools for creating and managing signing requests.

Tool	Description
`signing_requests_list`	List signing requests with filtering and pagination
`signing_requests_create`	Create a new signing request from a document or template
`signing_requests_create_and_send`	Create and send a signing request in one step
`signing_requests_get`	Get details of a specific signing request
`signing_requests_partial_update`	Update specific fields on a signing request
`signing_requests_update`	Full update of a signing request
`signing_requests_send`	Send a draft signing request to recipients
`signing_requests_cancel`	Cancel an active signing request
`signing_requests_resend`	Resend to specific recipients
`signing_requests_users_list`	List recipients on a signing request
`signing_requests_fields_list`	List fields on a signing request
`signing_requests_reminders_list`	List reminders for a signing request
`signing_requests_audit_list`	Get the audit trail for a signing request

Create and manage reusable document templates.

Tool	Description
`templates_list`	List templates with filtering and pagination
`templates_create`	Create a new template from a base64-encoded document
`templates_get`	Get details of a specific template
`templates_partial_update`	Update specific fields on a template
`templates_update`	Full update of a template
`templates_delete`	Delete a template
`templates_duplicate`	Duplicate a template into a new signing request
`templates_replace_document`	Replace the document on an existing template
`templates_users_list`	List recipients on a template
`templates_fields_list`	List fields on a template
`templates_reminders_list`	List reminders on a template

Manage workspaces for multi-tenant isolation.

Tool	Description
`workspaces_list`	List all workspaces
`workspaces_create`	Create a new workspace
`workspaces_get`	Get details of a specific workspace
`workspaces_update`	Full update of a workspace
`workspaces_partial_update`	Update specific fields on a workspace
`workspaces_api_key_regenerate`	Regenerate a workspace’s API key
`workspaces_api_key_expire`	Expire pending API keys
`select_workspace`	Switch the active workspace for the session

Configure webhook endpoints for real-time event notifications.

Tool	Description
`webhooks_list`	List all webhooks
`webhooks_create`	Create a new webhook
`webhooks_get`	Get details of a specific webhook
`webhooks_update`	Update a webhook
`webhooks_delete`	Delete a webhook
`webhooks_test`	Send a test event to a webhook
`webhooks_rotate_secret`	Rotate the webhook signing secret
`webhooks_secret_status`	Check webhook secret rotation status

View and update company-level information.

Tool	Description
`company_list`	Get company information
`company_update`	Full update of company details
`company_partial_update`	Update specific company fields

Configure custom email domains for sending notifications.

Tool	Description
`company_domains_list`	List company-level domains
`company_domains_create`	Add a company domain
`company_domains_get`	Get domain details
`company_domains_delete`	Remove a domain
`company_domains_verify_ownership`	Verify domain ownership
`company_domains_finalize`	Finalize domain setup
`company_domains_verify_dns`	Verify DNS records
`company_domains_set_primary`	Set as primary sending domain
`workspace_domains_list`	List workspace-level domains
`workspace_domains_create`	Add a workspace domain
`workspace_domains_get`	Get workspace domain details
`workspace_domains_delete`	Remove a workspace domain
`workspace_domains_verify_ownership`	Verify workspace domain ownership
`workspace_domains_finalize`	Finalize workspace domain setup
`workspace_domains_verify_dns`	Verify workspace domain DNS records
`workspace_domains_set_primary`	Set as primary workspace sending domain

Customize the email notifications sent to signers.

Tool	Description
`workspace_email_templates_list`	List workspace email templates
`workspace_email_templates_get`	Get a workspace email template
`workspace_email_templates_update`	Update a workspace email template
`workspace_email_templates_delete`	Reset a workspace email template to default
`company_email_templates_list`	List company email templates
`company_email_templates_update`	Update a company email template
`company_email_templates_delete`	Reset a company email template to default
`email_templates_defaults_get`	Get default email templates for a language
`email_templates_placeholders`	List available email template placeholders

Manage custom metadata fields on workspaces, templates, and signing requests.

Tool	Description
`workspace_custom_fields_list`	List workspace custom fields
`workspace_custom_fields_create`	Create a workspace custom field
`workspace_custom_fields_update`	Update a workspace custom field
`workspace_custom_fields_delete`	Delete a workspace custom field
`templates_custom_fields_list`	List template custom fields
`templates_custom_fields_create`	Create a template custom field
`templates_custom_fields_delete`	Delete a template custom field
`signing_requests_custom_fields_list`	List signing request custom fields
`signing_requests_custom_fields_create`	Create a signing request custom field
`signing_requests_custom_fields_delete`	Delete a signing request custom field

Generate JWT tokens for embedded editors and manage workspace settings.

Tool	Description
`generate_template_token_create`	Generate a JWT for the embedded template editor
`revoke_template_token_create`	Revoke a template JWT
`jwt_generate_signing_request_create`	Generate a JWT for the embedded signing request editor
`jwt_revoke_signing_request_create`	Revoke a signing request JWT
`workspace_settings_list`	Get workspace settings
`workspace_settings_update`	Update workspace settings

Workspace selection

After signing in to the Data MCP, you start without a workspace selected. You can either:

Ask the assistant to select a workspace - e.g., “Switch to the Marketing workspace”
Let the assistant pass a workspace ID per request - the assistant can include a workspace_id parameter on individual tool calls

The assistant will typically list your workspaces first and ask which one to use.

Example conversations

List all signing requests

“Show me all pending signing requests in my Marketing workspace”

The assistant will select the workspace, call the signing requests list endpoint, and present the results.

Create and send a signing request

“Create a signing request from the NDA template and send it to jane@example.com”

The assistant will find the template, duplicate it into a signing request, set the recipient, and send it.

Check signing status

“What’s the status of the signing request I sent to John last week?”

The assistant will search recent signing requests and return the current status, including which recipients have signed.

Generate integration code

“Using the Firma docs, create a Next.js API route that sends a signing request using the create-and-send endpoint”

The assistant will query the Docs MCP for the correct endpoint, request shape, and auth pattern, then generate working code.

Rate limits

MCP requests are subject to the same rate limits as direct API calls. Each tool call maps to one API request. The Docs MCP server has no rate limits.

Troubleshooting

Tools not loading

If your client shows the server as connected but no tools appear:

Claude.ai / ChatGPT: Try disconnecting and reconnecting the connector from Settings
Cursor / VS Code: Restart the application after adding the configuration
Claude Desktop: Restart the app - changes to claude_desktop_config.json require a restart

Workspace not found

Make sure you’ve selected a workspace after connecting to the Data MCP. Use “List my workspaces” to see available options.

Authentication errors

Try signing out and back in to refresh your session. If the issue persists, disconnect and reconnect the server in your client’s settings. The Docs MCP does not require authentication.

​What is MCP?

​Setup

Add Firma to Claude.ai

Add Firma to ChatGPT

Install in Cursor

Install in VS Code

Add Firma Docs to Claude.ai

Add Firma Docs to ChatGPT

​What the Docs MCP provides

​When to use it

​Data MCP: Available tools

​Workspace selection

​Example conversations

​List all signing requests

​Create and send a signing request

​Check signing status

​Generate integration code

​Rate limits

​Troubleshooting

​Tools not loading

​Workspace not found

​Authentication errors

What is MCP?

Setup

What the Docs MCP provides

When to use it

Data MCP: Available tools

Workspace selection

Example conversations

List all signing requests

Create and send a signing request

Check signing status

Generate integration code

Rate limits

Troubleshooting

Tools not loading

Workspace not found

Authentication errors