Skip to main content
n8n Logo

Using Needle MCP Tools in n8n with AI Agent

7 min read

One of the best ways to integrate Needle's powerful semantic search capabilities into your automation workflows is via n8n's AI Agent with MCP support.

Model Context Protocol (MCP) standardizes the way LLMs connect to external data sources.

You can use Needle MCP Server to easily enable semantic search tools in your n8n AI workflows. Making the data buried in PDFs, DOCX, XLSX, and other files instantly accessible by LLMs through natural chat interactions.

The Needle MCP Server is open source and available on GitHub: needle-ai/needle-mcp

What is n8n?​

n8n is an open-source workflow automation tool that allows you to connect different services and automate tasks. With MCP support, you can now integrate AI tools like Needle directly into your workflows.

What You'll Be Able to Do​

Once set up, your AI agent will be able to:

  • Query Needle collections via AI chat
  • List collections (needle_list_collections)
  • Get collection metadata and statistics
  • Perform semantic search on a collection
  • Upload, delete, or list files in collections
  • Enable agents to reason over your document store autonomously

Prerequisites​

Before setting up the integration, make sure you have:

  • An active n8n instance (cloud or self-hosted)
  • Self-hosted n8n? Run npm install n8n-nodes-mcp to get the MCP Client node
  • A Needle API key (get one from Needle Settings)
  • At least one Needle collection with indexed documents
  • OpenAI API key for GPT-4 Turbo (gpt-4-turbo recommended for tool calling)

Setting Up Needle MCP in n8n with AI Agent​

Tech Stack​

  • n8n (Cloud or self-hosted)
  • AI Agent node (with tool support)
  • MCP Client node (connecting to remote MCP server)
  • Needle MCP Server (Remote): https://mcp.needle-ai.com/sse
  • OpenAI Chat Model (gpt-4-turbo recommended for reliable tool calling)
  • Simple Memory (for conversation context)
  • Needle API Key (for OAuth header authentication)

Step 1: Get Your Needle API Key​

  1. Go to Needle Settings
  2. Generate a new API Key
  3. Copy and save it securely

Step 2: Create OAuth Header Credential in n8n​

  1. Go to Credentials in your n8n instance
  2. Add a new HTTP Header Auth credential:
    • Name: Needle MCP Auth
    • Header Name: Authorization
    • Header Value: Bearer YOUR_NEEDLE_API_KEY
Needle Settings Page for API Key Generation

Generate your Needle API key from the Settings page.

 n8n Header Auth Configuration with Bearer Token

Configure Header Auth credential with Authorization header and Bearer token.

Step 3: Set Up Your Data Sources and Collections​

Before configuring n8n, you need to populate your Needle collections with relevant data that your AI agent can use as context. This is crucial for the agent to provide meaningful responses.

Recommended Data Sources:

  1. Gmail - Connect your email for accessing correspondence, attachments, and communication history
  2. Google Drive - Import documents, spreadsheets, presentations, and other files
  3. PDF Documents - Upload multiple PDFs with manuals, reports, contracts, or knowledge base content
  4. Web Pages - Add important websites, documentation, or online resources

To set up connectors:

  1. Go to Needle Collections
  2. Create a new collection or select an existing one
  3. Navigate to Connectors and choose from available options:
Needle Connectors Page showing available data sources

Available Needle connectors including Gmail, Google Drive, and many other data sources.

💡 Pro Tip: The more relevant data you add to your collections, the more context your n8n AI agent will have to provide accurate and helpful responses. Consider adding company documents, FAQs, product manuals, and communication archives.

Step 4: Create Your n8n Workflow​

Build the following workflow structure:

Chat Trigger → AI Agent
               ↓
    ┌─────────────────────┐
    │   AI Agent Node     │
    │                     │
    │  Connected to:      │
    │  • OpenAI Chat      │
    │  • Simple Memory    │
    │  • MCP Client       │
    └─────────────────────┘

Required nodes:

  1. Chat Trigger - Handles incoming chat messages from users
  2. AI Agent - The core reasoning engine that uses tools
  3. OpenAI Chat Model - Language model (gpt-4-turbo recommended)
  4. Simple Memory - Maintains conversation context
  5. MCP Client - Connects to Needle's remote MCP server
n8n Workflow Graph with Needle MCP Integration

Complete n8n workflow showing Chat Trigger connected to AI Agent with OpenAI Chat Model, Simple Memory, and MCP Client.

Step 5: Configure Chat Trigger​

  1. Add a Chat Trigger node as your workflow entry point
  2. Configure basic settings:
    • Trigger on: Message Received
    • Response: Enable to send responses back to chat
    • Options: Set according to your chat interface needs

Step 6: Configure MCP Client Node​

  1. Add the MCP Client node to your workflow
  2. Essential Configuration:
SettingValue
SSE Endpointhttps://mcp.needle-ai.com/sse
AuthenticationSelect your Needle MCP Auth credential
Connection TypeRemote MCP Server

📌 Endpoint Recommendation: Use the SSE endpoint https://mcp.needle-ai.com/sse as this is the working endpoint for n8n's MCP Client node.

Step 7: Configure AI Agent Node​

  1. Connect the AI Agent to these components:
ConnectionNodePurpose
ModelOpenAI Chat ModelSet to gpt-4o-turbo or gpt-4-1106-preview (both support tool calling)
MemorySimple MemoryMaintains conversation context
ToolsMCP ClientProvides Needle search capabilities
InputChat TriggerReceives user messages
  1. Agent Configuration:
    • Output Format: Set to "Auto" (not specific format required)
    • System Message: Optional - customize the agent's behavior
    • Max Iterations: Default (or adjust based on your needs)

Step 8: Test Your Setup​

Activate your workflow and try these chat prompts:

📋 Collection Management​

"List my Needle collections"
"Show me the stats for my main collection" 
"Create a new collection called 'Customer Docs'"

🔍 Semantic Search​

"Search my documents for information about GDPR compliance"
"Find meeting notes from last week about the product launch"
"What documents mention pricing strategies?"

📁 File Operations​

"Add this PDF to my collection: https://example.com/report.pdf"
"Can you add https://needle-ai.com to the collection?"
"List all files in my 'Legal' collection"
"Remove the outdated contract from my collection"

💡 How it works: The AI agent receives your chat message, determines which Needle tools to use, calls the MCP server, and returns natural language responses with the search results.

Real Workflow Example​

Here's a complete example of adding a website URL to a Needle collection through the n8n workflow. In this example, we're asking the AI agent to add the Needle AI homepage to a collection:

n8n Workflow Adding File via URL

Live workflow execution showing the AI agent successfully adding https://needle-ai.com to a Needle collection.

What happened in this workflow:

  1. User Input: "Can you add https://needle-ai.com to the collection?"
  2. AI Agent Processing: The AI agent recognized this as a file addition request
  3. MCP Tool Call: Used needle_add_file_to_collection with the URL
  4. Response: "The file 'Needle AI Homepage' pointing to 'https://needle-ai.com' has been successfully added to the collection 'Needle Drive Sales.' The file is currently pending for data retrieval and indexing."

After the file is processed, you can see it indexed in your Needle collection:

Needle Homepage Successfully Indexed

Needle AI Homepage successfully indexed and available for semantic search in the collection.

Final Result:

  • File Status: Successfully indexed (649.5 KB)
  • Collection: "Needle Drive Sales"
  • Source: Manual upload via n8n workflow
  • Ready for Search: The webpage content is now available for semantic search through any Needle interface

This demonstrates the complete end-to-end workflow: from chat input in n8n to indexed content in Needle, ready for AI-powered search and retrieval.

Available Needle Tools in n8n​

Once configured, you'll have access to all Needle MCP tools in your n8n workflows:

Core Tools​

  • needle_list_collections - List all your Needle collections
  • needle_get_collection_details - Get details about a specific collection
  • needle_search - Perform semantic search on a collection

File Management​

  • needle_add_file - Add files to collections
  • needle_list_files - List files in a collection

Analytics​

  • needle_get_collection_stats - Get collection statistics and insights

Example Workflow Use Cases​

1. Document Processing Pipeline​

Create a workflow that:

  1. Monitors a folder for new documents
  2. Automatically adds them to a Needle collection
  3. Sends a notification when indexing is complete

2. Customer Support Automation​

Build a workflow that:

  1. Receives customer inquiries
  2. Searches your knowledge base using Needle
  3. Provides relevant answers or escalates to human agents

3. Content Research Assistant​

Develop a workflow that:

  1. Takes research queries as input
  2. Searches multiple Needle collections
  3. Compiles and formats the results
  4. Sends summarized findings via email or Slack

Best Practices​

OpenAI Model Selection​

  • Recommended model: Use gpt-4-turbo for the best tool calling performance and reliability
  • Alternative models: gpt-4-1106-preview (GPT-4 Turbo) or gpt-3.5-turbo-1106 also support tool calling

MCP Tool Configuration​

  • JSON Schema: MCP tools can declare their inputs with either inputSchema (Needle style) or parameters (OpenAI style)
  • Input validation: Ensure tool inputs match the expected keys (e.g., collection_id, query, offset)
  • Clear prompts: Use clear prompts that guide the LLM to match those input keys

API Key Security​

  • Always use environment variables for your API keys
  • Never commit API keys to version control
  • Rotate your API keys regularly
  • Use different API keys for different environments (dev, staging, production)

Workflow Design​

  • Error Handling: Always include error handling nodes for MCP calls
  • Rate Limiting: Be mindful of API rate limits in high-frequency workflows
  • Caching: Consider caching search results for frequently accessed data
  • Monitoring: Set up monitoring for your MCP-enabled workflows

Troubleshooting​

Common Issues​

Tool Input Schema Errors​

  • Error: "Received tool input did not match expected schema"
  • Solution: Double-check that tool inputs match the expected keys (e.g., collection_id, query, offset)
  • Tip: Use clear prompts that guide the LLM to match those input keys exactly

🔧 Special Case: For needle_list_collections, open AI Agent → Tools, set Fixed JSON arguments to {}. This avoids the schema error if you can't alter the server.

MCP Client Node Configuration​

  • Error: MCP tools not appearing or failing to execute
  • Solution: Verify your MCP endpoint is set to https://mcp.needle-ai.com/sse
  • Solution: Ensure your HTTP Header Auth credential is properly configured with Authorization header
  • Solution: Check that you've selected the right tools in the "Tools to Include" list

OpenAI Model Compatibility​

  • Error: Tools not being called or function calling not working
  • Solution: Make sure you're using a compatible OpenAI model: gpt-4-turbo (recommended), gpt-4-1106-preview (GPT-4 Turbo), or gpt-3.5-turbo-1106
  • Avoid: Older models that don't support function calling

Authentication Errors​

  • Confirm your Needle API key has the necessary permissions
  • Check that the Authorization header format is Bearer YOUR_API_KEY
  • Verify your API key hasn't expired

Tool Calls Failing​

  • Ensure collection IDs exist and are accessible
  • Check that your API key has access to the specific collections
  • Verify network connectivity to mcp.needle-ai.com

Getting Help​

If you encounter issues:

  1. Check the n8n logs for detailed error messages
  2. Verify your Needle API key works in other contexts
  3. Test the MCP server connection outside of n8n
  4. Check the needle-mcp GitHub repository for the latest updates and troubleshooting

Support​

If you need help with the n8n integration:

For n8n-specific questions, also consider: