# Needle MCP

Needle MCP server (v1).

The same outbound engine as the REST API, as tools your agent can call. Works with Claude Code, Cowork, Codex, Cursor, Hermes, or any MCP client.

Prefer HTTP? See the [API Reference](/docs/api-reference/introduction). New here? Start at the [onboarding skill](/agent-onboarding/SKILL.md).

## Set up Needle MCP

Add an API key to connect. Create a key in the dashboard under [API keys](/api-keys).

### Claude Code

Run this in your terminal to add Needle as a remote MCP server in Claude Code.

```bash
claude mcp add --transport http needle undefined/mcp/v1 --header "Authorization: Bearer sk-ndl-…"
```

Then enter `/mcp` in Claude Code and confirm **needle** is connected.

### Codex

Run this in your terminal to add Needle as a remote MCP server in Codex.

```bash
codex mcp add needle --url undefined/mcp/v1 --bearer-token-env-var NEEDLE_API_KEY
```

Set `NEEDLE_API_KEY` to your API key, then run `codex mcp list` and confirm **needle** is enabled.

### Cursor

Add Needle to Cursor, then replace the placeholder with your API key.

[Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=needle&config=eyJ1cmwiOiJ1bmRlZmluZWQvbWNwL3YxIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIHNrLW5kbC0uLi4ifX0=)

```json
{
  "mcpServers": {
    "needle": {
      "url": "undefined/mcp/v1",
      "headers": {
        "Authorization": "Bearer sk-ndl-…"
      }
    }
  }
}
```

Replace `sk-ndl-…` in `.cursor/mcp.json` or `~/.cursor/mcp.json`, then reload MCP servers.

### OpenCode

Add this to `opencode.json`.

```json
{
  "mcp": {
    "needle": {
      "type": "remote",
      "url": "undefined/mcp/v1",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer sk-ndl-…"
      }
    }
  }
}
```

Replace `sk-ndl-…` with your API key. `oauth` is `false` so OpenCode uses the bearer header.

### Another client

Point any MCP client at `undefined/mcp/v1` with `Authorization: Bearer sk-ndl-…`.

## Features

- **Leads**: Build lead lists from LinkedIn and the Places API.
- **Campaigns**: Run multi-channel, multi-account outreach on LinkedIn and Instagram.
- **LinkedIn**: Search people and run outreach from connected accounts.
- **Instagram**: Reach people on Instagram from connected accounts.
- **Events**: Search activity across campaigns, leads, and connected accounts.
- **Places**: Find companies and locations to source lists.
- **Connected Accounts**: Connect LinkedIn and Instagram accounts to send from.
- **Suppressions**: Keep people and companies you should not contact off the list.
- **Compose**: Preview a message before you send it.

## Authentication

Call tools with `Authorization: Bearer sk-ndl-…`. Create a key in the dashboard under API keys. Each key is bound to one user and one organization. Listing tools at `/mcp/v1/tools` does not require a key.

## Tools

### Me

- [Get the authenticated user](/docs/mcp/needle-get-me)

### Connected accounts

- [List connected accounts](/docs/mcp/needle-list-connected-accounts)
- [Get a connected account](/docs/mcp/needle-get-connected-account)
- [Update a connected account](/docs/mcp/needle-update-connected-account)
- [Delete a connected account](/docs/mcp/needle-delete-connected-account)
- [List connected account events](/docs/mcp/needle-list-connected-account-events)

### Leads

- [List leads](/docs/mcp/needle-list-leads)
- [Create a lead](/docs/mcp/needle-create-lead)
- [Get a lead](/docs/mcp/needle-get-lead)
- [Update a lead](/docs/mcp/needle-update-lead)
- [Delete a lead](/docs/mcp/needle-delete-lead)
- [List lead events](/docs/mcp/needle-list-lead-events)

### Campaigns

- [List campaigns](/docs/mcp/needle-list-campaigns)
- [Create a campaign](/docs/mcp/needle-create-campaign)
- [Get a campaign](/docs/mcp/needle-get-campaign)
- [Update a campaign](/docs/mcp/needle-update-campaign)
- [Archive a campaign](/docs/mcp/needle-archive-campaign)
- [Get campaign stats](/docs/mcp/needle-get-campaign-stats)
- [List campaign events](/docs/mcp/needle-list-campaign-events)
- [List campaign leads](/docs/mcp/needle-list-campaign-leads)
- [Enroll leads](/docs/mcp/needle-enroll-campaign-leads)
- [Stop a lead in a campaign](/docs/mcp/needle-remove-campaign-lead)
- [List pending approvals](/docs/mcp/needle-list-pending-approvals)
- [Approve a pending send](/docs/mcp/needle-approve-pending-task)

### Events

- [Search events](/docs/mcp/needle-search-events)

### LinkedIn

- [Get a LinkedIn profile](/docs/mcp/needle-get-linkedin-profile)
- [Search LinkedIn people](/docs/mcp/needle-search-linkedin-people)
- [Send a LinkedIn message](/docs/mcp/needle-send-linkedin-message)
- [List messages in a conversation](/docs/mcp/needle-list-linkedin-conversation-messages)
- [List pending invitations](/docs/mcp/needle-list-linkedin-invitations)
- [Send a connection invitation](/docs/mcp/needle-send-linkedin-invitation)
- [Withdraw an invitation](/docs/mcp/needle-withdraw-linkedin-invitation)
- [List first-degree connections](/docs/mcp/needle-list-linkedin-relations)

### Instagram

- [Get an Instagram profile](/docs/mcp/needle-get-instagram-profile)
- [Send an Instagram message](/docs/mcp/needle-send-instagram-message)
- [List messages in a conversation](/docs/mcp/needle-list-instagram-conversation-messages)
- [Follow an Instagram user](/docs/mcp/needle-follow-instagram-user)
- [Unfollow an Instagram user](/docs/mcp/needle-unfollow-instagram-user)

### Places

- [Search places](/docs/mcp/needle-search-places)
- [Get a place](/docs/mcp/needle-get-place)

### Compose

- [Preview an AI-composed message](/docs/mcp/needle-compose-preview)

### Suppressions

- [List suppressions](/docs/mcp/needle-list-suppressions)
- [Create suppressions](/docs/mcp/needle-create-suppressions)
- [Check people and companies against the suppression list](/docs/mcp/needle-check-suppressions)
- [Delete a suppression](/docs/mcp/needle-delete-suppression)