Using MCP to connect AI tools to Firstbase – Firstbase

The Firstbase MCP server lets you connect AI tools (such as Cursor, Claude, or ChatGPT Codex) to your Firstbase organization. Once connected, you can ask questions and take actions on your Firstbase data using natural language, without building a custom integration.

This guide walks you through enabling MCP for your organization, connecting your AI client, and controlling which capabilities your team can access. MCP settings are managed in API Access and apply to your whole organization.

For a full list of API capabilities, see Firstbase API: What's available and how to use it.

Enable MCP for your organization

To turn on MCP for your organization:

Sign in to Firstbase as an Admin.
In the side nav, open API & Integrations → API Access.
Select the MCP Tools tab.
Turn on the MCP Server toggle.

When you enable MCP, Firstbase sets up your organization's MCP connection, creates a dedicated server API token, and discovers the available tools. You can then copy the connection config and choose which tools are allowed in the permissions section below.

Note: Only admins with access to API Access can enable MCP. This setting applies to your entire organization.

Connect your AI client to Firstbase

After MCP is enabled:

On the MCP Tools tab, expand mcp_servers config.
Click Copy to copy the JSON configuration snippet.
Paste the snippet into your AI client's MCP settings. Examples:
- Cursor: MCP settings or mcp.json
- Claude Desktop: MCP server configuration
- ChatGPT Codex: MCP configuration in your workspace settings
Restart or reload your AI client if prompted.
When your client connects to Firstbase, sign in with your company SSO account when asked.

The configuration snippet contains only the Firstbase MCP endpoint URL. It does not include an API key. Authentication is handled through SSO when your client connects.

Each admin sets up the connection on their own computer. You all share the same org-wide tool permissions configured in MCP Tools.

Control which tools AI clients can access

On the MCP Tools tab, the permissions section below the MCP Server toggle lets you choose what AI clients can do in your organization.

Tools are grouped by area, for example:

Orders
Returns & Replacements
Inventory
People
Catalog & Packages
Shipments & Notices
Locations
ITAD

Within each group, you can turn individual tools on or off. Tools are labeled Read or Write. Use Enable all or Disable all to change an entire group at once.

Important: MCP permissions are org-wide. If you enable or disable a tool, that change applies to every admin in your organization who uses MCP. Permission changes are not personal settings.

Changes take effect immediately. Admins can only use tools that remain enabled.

Disable MCP for your organization

To turn off MCP entirely:

Go to API & Integrations → API Access → MCP Tools.
Turn off the MCP Server toggle.

This disables MCP for your organization and removes the server API token. AI clients will no longer be able to call Firstbase through MCP until an admin turns it back on.

Admins who already added the MCP config to their AI client do not need to remove it, but requests to Firstbase will fail until MCP is re-enabled. Turning MCP back on runs the setup flow again, including a new server token and tool discovery.

Frequently Asked Questions

What is the difference between API Credentials and MCP Tools?

Both tabs are under API Access, but they serve different purposes:

API Credentials is for traditional API integrations. You create and manage API tokens that authenticate direct requests to the Firstbase Public API (custom scripts, middleware, HRIS connectors, and similar).

MCP Tools is for AI agent access. You enable the MCP server, copy a connection config for your AI client, and control which tools AI assistants can use. Firstbase automatically creates a dedicated server token when MCP is enabled. You do not paste that token into your AI client.

Use API Credentials when you are building an integration. Use MCP Tools when you want to connect an AI assistant to Firstbase.

Are MCP settings org-wide or per admin?

MCP settings are org-wide.

The MCP Server on/off toggle applies to your entire organization.
Tool permissions are shared across all admins. If one admin enables or disables a tool, every admin who uses MCP is affected.

What is per admin is the connection to your AI client. Each admin copies the MCP config into their own tool (Cursor, Claude, etc.) and signs in with their own SSO account. Everyone operates under the same org-wide permission rules.

Which AI clients work with Firstbase MCP?

Any AI client that supports the Model Context Protocol and can connect to a remote MCP server over HTTP can work with Firstbase.

Commonly used clients include:

Cursor
Claude Desktop
ChatGPT Codex

The exact setup steps vary by client, but the process is the same: paste the mcp_servers config snippet from API Access into your client's MCP settings, then authenticate with your company SSO when prompted.

If your preferred tool supports MCP but is not listed here, check its documentation for how to add a remote MCP server.

Why am I getting a 403 or "not provisioned" error?

Common causes and fixes:

MCP is not enabled

Confirm MCP Server is turned on under API & Integrations → API Access → MCP Tools.

The tool is not permitted

The specific capability may be disabled in your org's MCP permissions. An admin can enable it on the MCP Tools tab.

You are not provisioned as an MCP user

You must be an active admin for the organization. Provisioning usually happens automatically when MCP is enabled. If you were recently added as an admin, try having another admin toggle MCP off and back on, or contact Firstbase Support.

Authentication issue

You may not have completed company SSO in your AI client, or your session may have expired. Re-authenticate in your AI client.

Wrong account

Confirm you signed in with the SSO account tied to the correct Firstbase organization.

If the error continues, note the exact message and check the Activity tab for more details before contacting Firstbase Support.

Can I see what actions were taken through MCP?

Yes. Open API & Integrations → API Access → Activity to view a log of MCP tool calls for your organization.

Each entry typically shows:

Whether the call succeeded or failed
Which admin triggered the call
The input arguments sent by the AI client
The result or error returned

You can filter by status to find failed calls when troubleshooting.

The Activity tab is read-only. Use MCP Tools to change permissions, and API Credentials to manage API tokens.

Do I need an API key in my MCP config file?

No. The configuration snippet you copy from MCP Tools contains only the Firstbase MCP endpoint URL. Do not add an API key to the file.

When your AI client connects, it will prompt you to authenticate with your company SSO account. Firstbase handles authentication automatically after you sign in.

Firstbase does create a dedicated server API token behind the scenes when MCP is enabled, but that token is managed by Firstbase. You do not need to copy or configure it in your AI client.

If you are building a direct API integration (not using MCP), use the API Credentials tab to create and manage tokens instead.

What happens if I disable a write tool but leave read tools enabled?

Read and write tools are controlled independently. If you disable a Write tool but leave Read tools enabled in the same area, AI clients can still look up data but cannot make changes through the disabled write tool.

For example, you might allow reading inventory but disable write operations that create or update records. An admin using MCP could ask "show me all laptops assigned to new hires" but could not use a disabled write tool to update an assignment.

Use Read tools when you want visibility without changes. Use Write tools only when you are comfortable with AI clients taking action on your behalf. You can enable or disable tools individually, or use Enable all / Disable all at the domain level.

Remember: permission changes apply to all admins in your organization.