Skip to main content

Needle MCP in Claude Code

3 min read

Connect Claude Code to Needle MCP to search your documentation, codebases, runbooks, and more—directly from your editor or terminal.

This guide shows a quick CLI setup, then verification and Skills so Claude knows when to search Needle.

Prerequisites​

  • Needle account and API key (Dashboard → Settings)
  • Claude Desktop or Cursor installed
  • Node.js and npx available

Needle MCP Server endpoints:

  • Streamable HTTP (recommended): https://mcp.needle.app/mcp
  • SSE (deprecated by MCP spec): https://mcp.needle.app/sse

Run the following in your terminal, replacing the token with your Needle API key.

Add MCP server
claude mcp add --transport http needle \
  https://mcp.needle.app/mcp \
  --header "Authorization:Bearer <YOUR_NEEDLE_API_KEY>"

Verify:

Verify MCP servers
claude mcp list

You should see an entry like:

needle  https://mcp.needle.app/mcp   ✓

Open Claude Code and start a chat:

> list my Needle collections

Skills help Claude decide when to search Needle and which collections to use.

Create a folder under your Claude skills directory and add SKILL.md:

mkdir -p ~/.claude/skills/search-docs
~/.claude/skills/search-docs/SKILL.md
# Skill: Search Needle Docs

## When to use
- When asked about internal APIs, runbooks, or troubleshooting
- When context is missing from the current chat

## How to use
1. Ask clarifying questions if the scope is ambiguous.
2. Use the Needle MCP to search these collections:
   - engineering-docs
   - product-specs
   - runbooks
3. Include citations in your answer with titles + URLs.

## Example prompts
- "Search engineering-docs for our webhook retry policy"
- "Find runbooks related to rate limit errors"

Open Claude Code and try:

> search my API docs for authentication flow

Troubleshooting​

  • Ensure your API key is valid and not expired.
  • If using Cursor, prefer NEEDLE_AUTH_HEADER (e.g., Authorization:${NEEDLE_AUTH_HEADER}).
  • If results are empty, verify the target collections exist and are indexed.
  • Use claude mcp list to confirm the server appears and is reachable.