Cursor · MCP Server

Cursor MCP Server: messaging and email in your IDE

Q: Where is the Cursor mcp.json file?

Two places: ~/.cursor/mcp.json in your home folder is the global configuration, available in every project; .cursor/mcp.json at the root of the folder you opened in Cursor is the project configuration. Cursor reads the project file first, then the global one. Both take the same mcpServers block.

Q: Does Cursor support remote MCP servers with custom headers?

Yes. A remote entry in mcp.json takes a url and a headers object, and Cursor resolves ${env:NAME} inside both. The Unipile server is exactly that: streamable HTTP at https://developer.unipile.com/mcp?branch=v2.0 with the X-API-KEY header. No npx, no local process, no Node version to manage.

One URL and one header add the Unipile MCP server to Cursor. Your agent then builds LinkedIn, WhatsApp and email features into your project and tests every call on your Development application. Nothing to install or run locally.

Build Now Copy the mcp.json config

7-day free trial, no credit card.

~/.cursor/mcp.json · unipile

Add LinkedIn account connection to my CRM.

Read endpointPOST /v2/auth/linkschema loaded

Added the connect route and the Settings button. The account ID is stored on the user.

3 files changed · tested on the Development app

Describe the next feature…

Use case

Add LinkedIn, WhatsApp and email to your product from Cursor

Add LinkedIn, WhatsApp, email or calendar to your product. Through the Unipile MCP server, Cursor reads the API reference, writes the code in your stack and tests every request.

Connect the Unipile MCP server to CursorUnipile MCP connected

Select the channels you want to connectdeveloper.unipile.com/mcp

Connect all channels9 channels

LinkedIn/v2/{account_id}/chats

WhatsApp/v2/{account_id}/chats

Instagram/v2/{account_id}/chats

Telegram/v2/{account_id}/chats

Gmail/v2/{account_id}/emails

Outlook/v2/{account_id}/emails

IMAP/v2/{account_id}/emails

Google Calendar/v2/{account_id}/calendars

Outlook Calendar/v2/{account_id}/calendars

↑↓navigate spaceselect ↵connectone URL, one header

mcp.json, global or project

Add the Unipile MCP server to Cursor

The server is remote: one URL over streamable HTTP and one header, nothing to run locally. Pick global or project, paste the block, save, and Cursor loads it.

Before you start: Cursor up to date, a Development application in the Unipile dashboard with a scoped Account API key, and one test account linked through Hosted Auth.

Global configuration~/.cursor/mcp.json

Project configuration.cursor/mcp.json (repository root)

Key from an environment variable${env:UNIPILE_API_KEY}

Global or project?Project when each repository needs its own scoped key. Cursor reads project first, then global.

~/.cursor/mcp.json

{ "mcpServers": { "unipile": { "url": "https://developer.unipile.com/mcp?branch=v2.0", "headers": { "X-API-KEY": "your-scoped-api-key" } } } }

{ "mcpServers": { "unipile": { "url": "https://developer.unipile.com/mcp?branch=v2.0", "headers": { "X-API-KEY": "${env:UNIPILE_API_KEY}" } } } }

Save the file and Cursor loads the server. ${env:NAME} works in url and headers, so the key never sits in the file.

Verify the connection

1Open Customize in the sidebar: the unipile server is listed and enabled.
2In the Cursor CLI, run agent mcp list, or /mcp list inside a session.
3In a chat, ask Using the Unipile MCP, list the endpoints for LinkedIn people search and their required parameters and expect real routes back.

Optional: install in one click Paste your scoped Account API key to get a link that opens Cursor with the server pre-filled. The key never leaves your browser.

Add Unipile to Cursor

Prompts, not glue code

Give your agent the prompt

Three integration jobs, each with the prompt to paste in Cursor, the endpoints the agent runs on https://api.unipile.com with your X-API-KEY, and what lands in your project.

Cursor · ats-appDevelopment app

Add LinkedIn messaging to my ATS: sync each recruiter's inbox and let them reply from the candidate page.

Search endpoints"chats messages send"3 matches

Run requestGET /v2/{account_id}/chats12 chats

Created linkedin/inbox-sync.ts (chats and messages upserted on the candidate, cursor pagination) and POST /candidates/:id/reply, which calls the send route with the chat's own account ID. Ran the sync on the Development app: 12 chats, 87 messages.3 files changed · tested on the Development app

Paste the prompt, review the diff

Cursor reads the chat and message contracts, writes the sync job and the reply endpoint, and runs the first requests on your Development application. WhatsApp, Instagram and Telegram use the same chat routes.

Endpoints the agent uses

GET/v2/{account_id}/chatsGET/v2/{account_id}/chats/{chat_id}/messagesPOST/v2/{account_id}/chats/{chat_id}/messages/send

Build a LinkedIn integration

Cursor · crm-appDevelopment app

Implement Unipile Hosted Auth in this React and Fastify app so users connect their own LinkedIn account from Settings.

Read endpointPOST /v2/auth/linkschema loaded

Run requestPOST /v2/auth/link201 · link

Added POST /api/accounts/connect in Fastify: it creates the auth link server-side and returns the hosted URL. The React Settings page opens it and, on return, stores the new account_id on the workspace. Verified on the Development app with a test LinkedIn account.4 files changed · connect flow tested end to end

Your users connect their own accounts, your app gets an account ID

Hosted Auth is the page Unipile serves so your users link their own accounts. The agent wires the link on your backend, the redirect on your frontend and the storage of the account ID.

Endpoints the agent uses

POST/v2/auth/linkPOST/v2/auth/intentGET/v2/accounts/{account_id}

Implement Hosted Auth with an agent

Cursor · support-consoleDevelopment app

Subscribe to new-message webhooks and build a unified LinkedIn, WhatsApp and email inbox, one thread list with the channel as a badge.

Read endpointPOST /v2/webhooks/endpoints/schema loaded

Run requestGET /v2/{account_id}/emails200 OK

Registered a webhook endpoint for message events on the Development app, added POST /webhooks/unipile that returns 200 immediately and queues the event, a Thread model that maps chats and email threads to one shape, and the thread list with channel badges. Sent a test message: the list updated in under a second.6 files changed · 3 channels in one list

Real time without polling, one list for messaging and email

The agent reads the chat and email contracts, designs one thread model, and writes the sync and the webhook receiver. It then checks the delivery log through the webhook conversations route.

Endpoints the agent uses

POST/v2/webhooks/endpoints/GET/v2/{account_id}/chatsGET/v2/{account_id}/emailsGET/v2/webhooks/conversations/

Build a unified inbox with an agent

A Development application first Give Cursor a scoped key from a Development application, kept apart from Production.

Test accounts, real requests The agent runs requests on test accounts, on behalf of the authenticated user who linked them, within each provider's limits.

Validate each flow Check the connect flow, one read and one write per feature, and a webhook delivery.

Then switch to Production Nothing touches your users' accounts until you switch the key. See security and compliance.

Troubleshooting

Common errors and what they mean

The messages Cursor shows when an MCP entry is not right, and the fix for each.

No tools or prompts

Check the file you edited (~/.cursor/mcp.json or .cursor/mcp.json), remove any trailing comma, then reload the server from Customize.

No server info found

Use a remote entry with url set to exactly https://developer.unipile.com/mcp?branch=v2.0 and headers, without command or type: "stdio".

Connection failed

Check the host and ?branch=v2.0 for a typo, or a corporate proxy: the URL must answer in a browser, not 404.

401 Unauthorized on requests

Send a scoped Account API key from your Development application in headers, under the exact name X-API-KEY.

The project configuration is ignored

Put .cursor/mcp.json at the root of the folder you opened in Cursor, not in a subfolder.

Where to read the logs

Open the Output panel (Cmd+Shift+U on macOS, Ctrl+Shift+U on Windows and Linux) and select MCP Logs in the dropdown.

6000+ Companies Innovating with Unipile

Trusted by industry leaders

1 API

Streamline operations for all major communication channels

2 Days

Achieve live integration quickly with minimal setup

30%

Reduction in maintenance efforts and resources

Built-In Security and Compliance

Enterprise-grade protection for your data and workflows Learn more about our security

SOC 2 Type II

Certified

Independently audited security controls ensuring data protection and operational integrity.

GDPR

Compliant

Full compliance with European data protection regulations for user privacy.

99.9%

Platform Uptime over the last 24 months

24/7

Global Support with high-performance API

Cursor MCP server FAQ

The questions people actually type: where mcp.json lives, global or project, remote servers and headers, what to check when nothing shows up, keys, one-click install and the CLI.

Two places. ~/.cursor/mcp.json in your home folder is the global configuration, available in every project. .cursor/mcp.json at the root of the folder you opened in Cursor is the project configuration. Cursor reads the project file first, then the global one, then parent directories. Both take the same mcpServers block.

Globally when you build several Unipile integrations from one machine and one Development application. Per project when each repository needs its own scoped key, which is the right choice when Development and Production integrations live in different repositories. In both cases the key is a scoped Account API key, never a Service or global key.

Yes. A remote entry in mcp.json takes a url and a headers object, and Cursor resolves ${env:NAME} inside both. The Unipile server is exactly that: streamable HTTP at https://developer.unipile.com/mcp?branch=v2.0 with the X-API-KEY header. No npx, no local process, no Node version to manage.

In this order: the file you edited (global or project, at the repository root), the validity of the JSON, a reload of the server from Customize or a restart of Cursor, then the MCP Logs in the Output panel (Cmd+Shift+U, select MCP Logs). If the server connects but requests fail with 401, the key is missing from the header or is not a scoped Account API key.

The server answers without a key when the agent only reads the API specification. To run real requests, create a Scope in your Development application, assign the test accounts, and generate a scoped Account API key for that Scope. Never give an MCP client a Service key or a global Account key.

Yes. The install link on this page encodes the server configuration; it opens Cursor with the unipile entry pre-filled, and you replace the placeholder with your scoped key. The optional generator above builds the same link with your key already in it, entirely in your browser.

Yes. The CLI shares the editor's configuration, project first, then global. agent mcp list shows the configured servers and their status, and /mcp list does the same inside an interactive session. The agent then uses the Unipile server when a request calls for it.