Skip to main content

Cursor MCP Setup

Connect MCP servers to Cursor to give your AI coding assistant access to external tools — databases, CRMs, payment platforms, analytics, and 500+ other services.

Requirements​

  • Cursor (latest version recommended)
  • A bundle enabled in your MCPBundles dashboard
  • Credentials connected for the providers in your bundle

Time to complete: 2-3 minutes

Quick Start: One-Click Install​

The fastest way to add MCPBundles to Cursor — click this button and Cursor handles the rest:

Install MCPBundles in Cursor →

Cursor intercepts the link, shows you the server details (name, transport type, URL), and installs it. No JSON editing, no terminal commands.

After installing, Cursor will prompt you to authorize via OAuth. Click Connect, authorize in your browser, and your tools are ready.

Setup Methods​

The MCPBundles CLI gives you runtime tool discovery, cross-service scripting, and automatic config generation:

pip install mcpbundles
mcpbundles connect my_workspace
mcpbundles init

mcpbundles init writes a skill file into your project directory. Cursor reads it automatically. The agent discovers tools at runtime, so when your team adds a new service to the workspace later, the agent picks it up without any config changes.

After running mcpbundles init, restart Cursor and your tools will be available.

Want more control? Use mcpbundles tools to browse available tools, or mcpbundles call <tool-name> to test a tool directly from your terminal.

Option B: UI Setup​

  1. Open Cursor Settings → Tools & MCP
  2. Click "Add new MCP server"
  3. Set Type to streamableHttp
  4. Set URL to your bundle URL (e.g. https://mcp.mcpbundles.com/bundle/YOUR-BUNDLE-SLUG)
  5. Click Install
  6. Restart Cursor completely (quit and reopen — closing the window is not enough)

You can find your bundle URL in the MCPBundles Dashboard under the "Quick Setup" section of any enabled bundle.

Option C: Manual Config (mcp.json)​

1. Get Your Bundle URL​

  1. Log in to MCPBundles Dashboard
  2. Click on the bundle you want to use
  3. Scroll to the "Quick Setup" section (only visible when bundle is operational)
  4. Copy the MCP Server URL (looks like https://mcp.mcpbundles.com/bundle/YOUR-BUNDLE-SLUG)

2. Locate Your MCP Config File​

Cursor stores MCP server configuration in mcp.json at two levels:

ScopeLocationUse Case
Global~/.cursor/mcp.jsonTools available in all projects
Project.cursor/mcp.json in project rootProject-specific tools (commit to git for team sharing)

File paths by OS:

OSGlobal Path
macOS~/.cursor/mcp.json
Windows%USERPROFILE%\.cursor\mcp.json
Linux~/.cursor/mcp.json

If the file doesn't exist, create it.

3. Edit the Config File​

New file or empty file:

{
  "mcpServers": {
    "your-bundle-name": {
      "url": "https://mcp.mcpbundles.com/bundle/YOUR-BUNDLE-SLUG"
    }
  }
}

Adding to an existing file:

{
  "mcpServers": {
    "existing-server": {
      "url": "https://some-other-server.com"
    },
    "your-bundle-name": {
      "url": "https://mcp.mcpbundles.com/bundle/YOUR-BUNDLE-SLUG"
    }
  }
}

Replace your-bundle-name with a short identifier (no spaces, e.g. marketing-automation) and use your actual bundle URL.

4. Save and Restart Cursor​

  1. Save the mcp.json file
  2. Quit Cursor completely (not just close the window — MCP servers only reload on full restart)
  3. Reopen Cursor
  4. Wait 10-20 seconds for MCP servers to initialize

5. Confirm Tools Are Available​

Open the command palette (Cmd/Ctrl + Shift + P), type "MCP", and look for MCP-related commands. Or ask the agent: "What tools do you have access to?"

Transport Types​

Cursor supports two MCP transport methods:

TransportConfig KeyWhen to Use
Streamable HTTP"url": "https://..."Remote/hosted servers (MCPBundles, cloud MCP servers)
stdio"command": "npx" + "args": [...]Local server processes running on your machine

Streamable HTTP sends JSON-RPC messages over HTTP. This is what MCPBundles uses — no local process to manage, and OAuth authentication is handled at the transport layer.

stdio launches a local subprocess. Good for filesystem access, local databases, or development servers.

{
  "mcpServers": {
    "mcpbundles": {
      "url": "https://mcp.mcpbundles.com/bundle/abc123"
    },
    "local-postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

Configuration Examples​

Single Bundle​

{
  "mcpServers": {
    "marketing": {
      "url": "https://mcp.mcpbundles.com/bundle/abc123"
    }
  }
}

Multiple Bundles​

{
  "mcpServers": {
    "marketing": {
      "url": "https://mcp.mcpbundles.com/bundle/abc123"
    },
    "dev-tools": {
      "url": "https://mcp.mcpbundles.com/bundle/def456"
    },
    "crm": {
      "url": "https://mcp.mcpbundles.com/bundle/ghi789"
    }
  }
}

Cursor will have access to tools from all bundles simultaneously.

With Other MCP Servers​

MCPBundles works alongside other MCP servers:

{
  "mcpServers": {
    "mcpbundles-marketing": {
      "url": "https://mcp.mcpbundles.com/bundle/abc123"
    },
    "local-filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Environment Variables​

You can use environment variables in mcp.json:

{
  "mcpServers": {
    "marketing": {
      "url": "${MCP_BUNDLE_URL}"
    }
  }
}

Then set MCP_BUNDLE_URL in your shell:

export MCP_BUNDLE_URL="https://mcp.mcpbundles.com/bundle/abc123"

Useful for sharing config across team members, switching between staging/production, or keeping secrets out of version control.

CLI vs mcp.json — When to Use Each​

Both approaches work. Use whichever fits your workflow:

Use mcp.json when you have a single-service setup and want tools to appear directly in Cursor's agent tool list. Add the URL, restart Cursor, done.

Use the CLI when you need multi-service workflows. The exec command lets the agent write Python that calls tools from different services in a single script:

mcpbundles exec "
customers = await list_customers(bundle='stripe', limit=10)
for c in customers['data']:
    contact = await search_contacts(bundle='hubspot-crm', query=c['email'])
    print(c['email'], c['created'], len(contact.get('results', [])), 'HubSpot matches')
"

You can also combine them: use mcp.json for your primary bundle and the CLI for cross-service scripting and ad-hoc tool calls.

Using Tools in Cursor​

Once connected, Cursor's agent uses your tools when relevant to your tasks.

Example Prompts​

Fetch data for development:

"Get the latest campaign data from Smartlead and create a TypeScript interface for it"

Automate deployment:

"List my GitHub repos, find the one called 'api-server', and check if there are any open PRs"

CRM integration:

"Fetch the latest 10 contacts from HubSpot and generate a SQL migration to import them"

Cursor calls the relevant tools, gets real data, and uses it in code generation or analysis. Instead of hallucinating TypeScript interfaces for an API response shape, the agent calls the actual API, inspects the response, and generates types that match the production data exactly.

Background Agents​

Cursor's background agents have the same MCP tool access as inline sessions. This changes what's practical — instead of quick lookups, you can write prompts like:

"Audit our subscription billing. Pull all active subscriptions from Stripe, cross-reference with our database to find any where the Stripe status doesn't match our local status, check HubSpot for the deal stages of any mismatches, and write a report as a markdown file."

That's 40+ tool calls across three services. A background agent handles it asynchronously — you come back to a finished report.

If you set up via the CLI (mcpbundles init), the skill file in your project gives background agents the same tool access automatically.

Tool Limits​

Cursor enforces a limit of approximately 80 tools across all MCP servers. If you exceed this, Cursor warns you and may not send all tools to the agent.

The limit exists because AI models perform worse when given too many tools — they struggle to pick the right one and waste context window space on tool descriptions.

How to stay under the limit:

  • Use focused bundles instead of one massive server. A "Sales" bundle with 15 HubSpot tools, a "Content" bundle with analytics and SEO — each stays well under the limit.
  • Disable unused tools. Expand any MCP server in Settings → Tools & MCP and toggle individual tools on/off.
  • Remove servers you aren't using. If you added something weeks ago and haven't touched it, remove it.
  • Use the CLI for large tool sets. The MCPBundles CLI uses programmatic tool calling — AI discovers tools on-demand and writes code to orchestrate them. You get access to thousands of tools without hitting the limit because the agent only loads what it needs for each task.

Cursor-Specific MCP Features​

OAuth Authentication​

Cursor handles OAuth flows natively for MCP servers that support it. When you connect to a server that requires authentication, Cursor shows an authorization prompt — click Connect, authorize in your browser, and credentials are stored securely. No API keys to copy-paste.

Tool Call Visibility​

Cursor shows tool calls in the chat:

  • Tool name and parameters used
  • Results returned
  • Errors if any

Useful for debugging when tools don't behave as expected.

Context Awareness​

Cursor automatically uses tools based on the current file content, selected code, recent edits, and open files. If you have a campaigns.ts file open and ask "update this", the agent might call list_campaigns to get current data.

Code Generation with Live Data​

The agent can call a tool to get real data, inspect the structure, and generate TypeScript interfaces, mock data, and API client code that matches actual production responses. Field names, nesting, nullable fields — all correct on the first try.

MCP Prompts and Resources​

Cursor (v1.6+) supports additional MCP capabilities beyond tools:

  • Prompts — reusable workflow templates that appear as slash commands in the chat
  • Resources — structured data that the AI can fetch and inject automatically based on context

CLI Commands for MCP Management​

From Cursor's built-in CLI, you can manage MCP servers without editing config files:

  • /mcp enable <server> — enable an MCP server
  • /mcp disable <server> — disable an MCP server

Troubleshooting​

"MCP server connection failed"​

Cause: The URL is unreachable or invalid.

Fix:

  • Confirm the URL is exactly as shown in your dashboard (including https://)
  • Make sure the bundle is enabled in your dashboard
  • Copy the URL again from the dashboard to rule out typos

Tools don't appear after adding config​

Cause: Cursor hasn't reloaded the MCP config.

Fix:

  1. Quit Cursor completely (not just close window — MCP servers only load on full restart)
  2. Wait 5 seconds
  3. Reopen Cursor
  4. Wait 20 seconds for MCP to initialize
  5. Ask the agent "What tools do you have?"

"Authentication required" when calling a tool​

Cause: Provider credentials not connected.

Fix:

  1. Go to Dashboard → Providers
  2. Find the provider for that tool
  3. Click Connect and complete OAuth or add API key
  4. Try the tool again in Cursor

See Provider Credentials Guide.

OAuth keeps failing​

Cause: Browser state or extension interference.

Fix:

  • Clear the auth cache: Settings → MCP → Clear Credentials
  • Run the OAuth flow in an incognito/private window
  • If using MCPBundles, try reconnecting the credential in the Dashboard

JSON syntax error in mcp.json​

Symptom: Cursor shows "Invalid JSON" or doesn't load any MCP servers.

Common mistakes:

Missing comma between servers:

{
  "mcpServers": {
    "bundle1": { "url": "..." },
    "bundle2": { "url": "..." }
  }
}

Trailing comma after last server:

{
  "mcpServers": {
    "bundle": { "url": "..." }
  }
}

Use a JSON validator or open the file in VS Code to catch syntax errors.

Bundle shows "Needs Credentials" in dashboard​

Cause: Providers not connected.

Fix:

  1. Dashboard → Bundles → Your Bundle
  2. Scroll to the "Credentials" section
  3. Find provider cards marked "Not configured" or showing "Error" badges
  4. Click "Add Credential" on each provider card
  5. Complete OAuth or enter API key
  6. Select validation tool and click "Validate Now"
  7. Bundle status should become "Ready" with "Credentials valid" subtext

Tools work but return empty data​

Cause: Connected to the wrong account or no data exists.

Fix:

  1. Dashboard → Providers → Provider Name
  2. Confirm which account is connected (shown in provider details)
  3. If wrong account, click Reconnect and use correct account
  4. Confirm data exists in the provider's actual app (e.g., log in to HubSpot and confirm contacts exist)

Tips & Best Practices​

Naming Bundles​

Use descriptive, short names without spaces:

  • ✅ marketing-automation
  • ✅ dev-tools
  • ✅ crm-suite
  • ❌ my bundle with spaces
  • ❌ bundle-123-abc-xyz-really-long-name

Multiple Bundles vs Combined Bundle​

Use multiple bundles when different projects need different tools, or you want to limit tool access per workspace.

Use one combined bundle when you use the same tools across all projects and want simpler configuration.

Start Small​

Don't add 50 tools because they might be useful someday. Add the 10 you'll use this week. You can always add more later.

Cursor vs Claude Desktop​

Both support MCP. Here's how they compare:

CursorClaude Desktop
One-click installYesNo (JSON only)
OAuth flowsBuilt-inManual tokens
Tool limit~80~128
Per-project configYesNo (global only)
Background agentsYesNo
Code generation with tool dataYesNo

FAQ​

How do I add MCP tools to Cursor?​

Fastest: click the one-click install button above. Or run pip install mcpbundles && mcpbundles init in the terminal. Or add a bundle URL to ~/.cursor/mcp.json manually. All three work.

Do background agents work with MCP tools?​

Yes. If you used the CLI (mcpbundles init), the skill file in your project gives background agents the same access as inline sessions. Background agents are good for audits, data reconciliation, and multi-service reports.

Does the CLI work with other AI coding agents?​

Same CLI, same workflow. Works in Claude Code, Windsurf, and anything else with terminal access.

What's the difference between the CLI and mcp.json?​

mcp.json puts tools directly in Cursor's agent tool list — simple and native. The CLI adds runtime tool discovery and cross-service scripting (mcpbundles exec). You can use both at the same time.

Next Steps​

Need Help?​