# Needle — how to use (mcp.ai)

Connect your Needle account and use 16 tools for artificial intelligence straight from your AI agent. Connect with your own API key. Needle provides retrieval-augmented generation (RAG) tools that enable semantic search across your data, facilitating the development of AI agents and applications.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_needle?ms=1787293440000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `needle_add_files_to_collection`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/needle`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/needle/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/needle/add/files/to/collection` — Tool to add files to a collection by providing file URLs. Use when you need to add one or more files to an existing collection. URLs can be public or private (generated via the Files API).
  - body: { files: object[], collection_id: string }
- `POST https://api.mcp.ai/api/needle/add/files/to/local/connector` — Tool to add files to a local connector by providing file metadata. Use when you need to add external files to a connector using their URLs.
  - body: { files: object[], connector_id: string }
- `POST https://api.mcp.ai/api/needle/create/collection` — Tool to create a new collection. Use after confirming the collection name.
  - body: { name: string, metadata?: object, description?: string }
- `POST https://api.mcp.ai/api/needle/create/local/connector` — Tool to create a local connector that monitors specified folders on a device. Use when setting up file indexing from a local machine into Needle collections.
  - body: { os: string, cpu: string, name: string, folders: object[], device_name: string, device_model: string, serial_number: string, collection_ids: string[] }
- `POST https://api.mcp.ai/api/needle/delete/files/from/collection` — Tool to delete files from a specific collection by providing file IDs. Use after confirming valid file IDs to remove from the collection.
  - body: { file_ids: string[], collection_id: string }
- `POST https://api.mcp.ai/api/needle/delete/files/from/local/connector` — Tool to delete files from a local connector by filename or file IDs. Use when you need to remove files from a connector's local storage.
  - body: { by: string, name?: string, file_ids?: string[], connector_id: string }
- `POST https://api.mcp.ai/api/needle/get/collection` — Tool to retrieve details for a specific collection by its ID. Use when you need to get collection metadata including name, creation date, and search query count.
  - body: { collection_id: string }
- `POST https://api.mcp.ai/api/needle/get/collection/stats` — Tool to retrieve statistics for a specific collection by its ID. Use when you need document count, index size, and timestamps after confirming the collection exists. Zero document count is a valid res
  - body: { collection_id: string }
- `POST https://api.mcp.ai/api/needle/get/file/download/url` — Tool to get a short-lived signed private download URL for a Needle file. Use when you need to retrieve file content but the public storage URL requires authentication. The returned URL should be used 
  - body: { file_id: string }
- `POST https://api.mcp.ai/api/needle/get/file/upload/url` — Tool to get signed URLs for uploading local files to Needle. Use when you need to upload files to a collection. The upload URLs are valid for a short time, so upload files immediately after receiving 
  - body: { content_type: string[] }
- `POST https://api.mcp.ai/api/needle/get/local/connector` — Tool to retrieve details of a local connector by its ID. Use when you need information about a specific local connector's configuration, device details, and associated folders.
  - body: { connector_id: string }
- `POST https://api.mcp.ai/api/needle/list/collection/files` — Tool to list all files within a specific collection by its ID. Returns file metadata (including file URLs) only — not document text content; fetch file URLs separately to access content. Use when you 
  - body: { limit?: integer, offset?: integer, collection_id: string }
- `POST https://api.mcp.ai/api/needle/list/collections` — Tool to list collections. Use after authenticating with your API key to page through collections. Similar collection names can exist; always verify the correct `collection_id` from results before perf
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/needle/list/connectors` — Tool to list connectors. Use to retrieve all configured connectors in your account.
- `POST https://api.mcp.ai/api/needle/list/local/connectors` — Tool to list local connectors. Use to retrieve all local connectors configured in your Needle account.
- `POST https://api.mcp.ai/api/needle/search/collection` — Tool to perform semantic search within a specific Needle collection and return ranked results with source references. Use when you need to retrieve relevant content from a known collection using natur
  - body: { text: string, top_k?: integer, offset?: integer, options?: object, max_distance?: string, collection_id: string }

## Example prompts
- "What can I do in Needle?"
- "Show me a summary of my Needle account"

## More
- Page: https://mcp.ai/needle
- Agent spec (llms.txt): https://mcp.ai/needle/llms.txt
- Postman collection: https://mcp.ai/needle/postman.json