Pinecone MCP Server Cursor IDE Setup (2026): API Key Config for Vector Index Search & Upsert
Connect Pinecone's official developer MCP server to Cursor IDE: add a .cursor/mcp.json entry with your PINECONE_API_KEY, then search docs, list indexes, and upsert records from chat — plus why it only works with integrated-inference indexes, not raw vector search.
Pinecone MCP Server Cursor IDE Setup (2026)
How do you connect Pinecone to Cursor? Generate an API key from the Pinecone console, create a .cursor/mcp.json file in your project root with a pinecone entry running @pinecone-database/mcp via npx, and set PINECONE_API_KEY in its env block. Restart Cursor, and it can search Pinecone documentation, list and describe your indexes, and upsert or query records — without an API key it still works, but only for documentation search.
Pinecone's MCP server is scoped narrower than it sounds. It's built for developers working with Pinecone as part of their stack — configuring indexes, testing queries, checking stats — not as a general-purpose retrieval tool your app calls at runtime. If you're building a RAG pipeline, this MCP server helps you set it up and debug it from your editor; your production code still talks to Pinecone through its regular SDK, not through MCP.
What the Pinecone MCP Server Can Do
Once connected, typical prompts include:
The search-docs tool works even without an API key configured — it's Pinecone's documentation search, not account data. Everything else (listing indexes, upserting, querying) needs a valid key.
The One Limitation That Trips People Up: Integrated Inference Only
This is the detail worth reading before you spend time wiring this up: the Pinecone MCP server only supports indexes created with integrated inference — indexes where Pinecone handles embedding generation internally via a model you pick at creation time (like multilingual-e5-large). If you're running an older "bring your own embeddings" serverless index, or doing raw vector search where your app computes embeddings and sends vectors directly, the MCP server's upsert-records and search-records tools won't work against it. Assistants, standalone embeddings, and vector-only indexes are explicitly unsupported.
If you hit this, the fix isn't a config change — it's creating a new integrated-inference index (create-index-for-model handles this from chat) and migrating data into it, or accepting that MCP will only be useful for the documentation-search half of this integration against your existing index.
Prerequisites
node --version, and that npx is on your PATH (which npx)Step 1: Generate a Pinecone API Key
1. Log in to the Pinecone console
2. Go to your project's API Keys section
3. Create a new key (or copy an existing one)
Without an API key, the AI tool can still search Pinecone documentation — it just can't manage or query your actual indexes.
Step 2: Create .cursor/mcp.json
Unlike most integrations on this site that go in ~/.cursor/mcp.json (a global config), Pinecone's own setup docs default to a project-scoped file. Create .cursor/mcp.json in your project root:
{
"mcpServers": {
"pinecone": {
"command": "npx",
"args": [
"-y", "@pinecone-database/mcp"
],
"env": {
"PINECONE_API_KEY": "<your pinecone api key>"
}
}
}
}
To enable it globally instead — so it's available across every project, not just this one — put the same block in .cursor/mcp.json in your home directory rather than the project root.
Step 3: Verify in Cursor Settings
Check Cursor Settings → MCP to confirm the pinecone server shows as connected. Then test in chat:
List all my Pinecone indexes
If real index names come back, the API key is working. If nothing comes back but you don't see an error, try the documentation-only test instead:
Search the Pinecone docs for information about serverless indexes
That one works even if the API key step failed, so it's a useful way to isolate whether the problem is the npx process starting at all versus the key itself being rejected.
Available Tools
search-docs — Search the official Pinecone documentation. Works without an API key.list-indexes — Lists all Pinecone indexes in the connected project.describe-index — Describes a specific index's configuration (dimension, metric, embedding model).describe-index-stats — Record counts and namespaces for an index.create-index-for-model — Creates a new integrated-inference index using a specified embedding model.upsert-records — Inserts or updates records in an index, with Pinecone handling embedding via integrated inference.search-records — Text-query search against an index using integrated inference, with metadata filtering and reranking options.cascading-search — Searches across multiple indexes at once, deduplicating and reranking combined results.rerank-documents — Reranks a set of records or raw text documents with a dedicated reranking model.Practical Workflows
Set Up a New Index for a RAG Feature
Create a new Pinecone index called 'product-docs' using the
multilingual-e5-large model, then upsert these 10 sample documents
into it so I can test retrieval quality before building the real ingestion pipeline.
Debug Poor Retrieval Results
Search my product-docs index for "return policy for opened items"
and show me the raw scores. If the top result doesn't look right,
suggest what metadata filter I could add to narrow it down.
Check Index Health Before a Migration
Describe the stats for my production index — how many records,
what namespaces, and does anything look unusually empty?
Cross-Index Search
Run a cascading search for "refund eligibility" across my support-docs
and product-docs indexes, and tell me which index the best result came from.
Troubleshooting
MCP server doesn't appear in Cursor
Confirm Node.js 18+ is installed (node --version) and npx is on your PATH (which npx). Check that .cursor/mcp.json is valid JSON — a trailing comma is the most common break — and restart Cursor after any config change.
"Invalid API key" or authentication errors
Verify the key in the Pinecone console matches what's in PINECONE_API_KEY exactly, with no extra spaces or surrounding quotes leaking into the value.
Tools return an error about unsupported index type
You're pointing at an index without integrated inference — a standalone-embeddings or vector-only index. upsert-records and search-records only work against integrated-inference indexes. Create a new index with create-index-for-model instead of trying to make these tools work against an existing raw-vector index.
Connection issues on a corporate network
Confirm your firewall allows outbound connections to api.pinecone.io. To see detailed error output, run the server manually: PINECONE_API_KEY=<your-key> npx @pinecone-database/mcp.
Global vs. project config conflict
If you have .cursor/mcp.json in both your home directory and a project root with different Pinecone entries, Cursor's project-level config takes precedence for that project — check which file you actually edited if a change doesn't seem to take effect.
Frequently Asked Questions
Q: Do I need a Pinecone API key just to search the documentation?
A: No. The search-docs tool works without any API key configured — it queries Pinecone's public documentation, not your account. You only need PINECONE_API_KEY for tools that touch your actual indexes: listing, describing, upserting, or searching records.
Q: Why can't I upsert records into my existing Pinecone index through MCP?
A: The MCP server only supports indexes built with integrated inference, where Pinecone generates embeddings internally from a model you selected at index creation. If your index uses standalone embeddings or raw vector search — you compute and send vectors yourself — upsert-records and search-records won't work against it. You'd need a new integrated-inference index instead.
Q: Is this MCP server meant to replace the Pinecone SDK in my application code?
A: No. It's built for the development workflow — configuring indexes, testing retrieval quality, checking stats from your editor. Production code that queries Pinecone at runtime should still use the regular Pinecone SDK directly, not go through an MCP connection meant for an AI coding assistant.
Q: Should this go in my global ~/.cursor/mcp.json or a project-level .cursor/mcp.json?
A: Pinecone's own setup instructions default to a project-level .cursor/mcp.json in the project root, which scopes the Pinecone connection (and its API key) to that specific codebase. Use the home-directory version instead if you want the same Pinecone project available across everything you work on in Cursor.
Q: Does this work with Pinecone Assistant, the RAG-focused product, instead of raw indexes?
A: No — this is the Developer MCP server, focused on indexes and documentation search. Pinecone offers a separate Assistant MCP server designed to give AI assistants context sourced from a knowledge base built in Pinecone Assistant; it's a different package with a different scope than the one this guide sets up.
Q: What happens if my PINECONE_API_KEY gets exposed in a committed config file?
A: Revoke it immediately from the API Keys section of the Pinecone console and generate a new one. Since the key can create, upsert into, and delete indexes (not just read), treat it as a real credential — keep .cursor/mcp.json out of version control if it contains the key directly, or reference an environment variable instead of hardcoding the value.
Related Guides
---