Needl MCP Server

Overview

The Needl MCP server brings Needl's enterprise search and Q&A into MCP-compatible clients such as Claude Desktop, ChatGPT, Cursor, and others. From a single tool, users can query Needl across:

Capital markets and regulatory filings — BSE/NSE (India), SEC/EDGAR (US), and NZX (New Zealand): annual reports, quarterly results, 10-K / 10-Q / 8-K, proxy statements, earnings call transcripts, investor presentations, board resolutions, shareholding patterns, corporate announcements.
Financial data and market intelligence — company financials, ratios, valuations, peer comparisons, sector trends, IPOs / M&A / fundraising events, due diligence.
The user's own connected data sources — Gmail, Outlook, Slack, Microsoft Teams, Google Drive, OneDrive, Dropbox, and other apps the user has linked to Needl. Searches across emails, messages, documents, and files.
Live web — optional internet search when the answer needs current public web information.

All answers are returned with source citations.

Server URL: https://mcp.needl.ai/mcp

Protocol: Model Context Protocol (MCP) over Streamable HTTP

Authentication: OAuth 2.0 with PKCE (handled automatically by your MCP client)

Available Tools

1. ask_needl

Unified search and Q&A across capital markets, regulatory filings, the user's connected private data, and optionally the live web.

Description: One tool for any user question — handles company financials and ratios (revenue, EBITDA, margins, P/E, ROE, balance sheet, cash flow), regulatory filings (10-K, 10-Q, 8-K, earnings transcripts, investor presentations, board resolutions, shareholding patterns), capital markets (BSE/NSE, SEC/EDGAR, NZX), market events (IPO, M&A, fundraising), peer and sector analysis, due diligence, and the user's own emails / messages / files. Returns cited results and a session_id so follow-up questions can continue the same conversation.

Parameters:

prompt (string, required): The user message to send.
session_id (string, required): UUID v4 session identifier.
- For a new conversation, generate a fresh UUID v4 (e.g. Python uuid.uuid4()).
- To continue an existing conversation, reuse the session_id returned by the previous response.
- Do not use placeholder or example UUIDs.
web_search (boolean, optional, default: false): Enable web search to include results from the internet alongside Needl's indexed data.

Response:

assistant_message is the answer text; raw_data carries the sentence-level citations, the deduplicated citation list, source documents, follow-up questions, and answer quality.

{
  "assistant_message": "Based on your data, here are the key trends in AI.",
  "session_id": "c8a3e1f0-7b2d-4e9a-8f6c-1d5a0e3b7c9f",
  "raw_data": {
    "assistant_message": "Based on your data, here are the key trends in AI.",
    "session_id": "c8a3e1f0-7b2d-4e9a-8f6c-1d5a0e3b7c9f",
    "assistant_message_with_citations": [
      {
        "sentence": "Based on your data, here are the key trends in AI.",
        "citations": [
          {
            "id": "…",
            "context": "…",
            "url": "https://example.com/source",
            "title": "Source title",
            "source": "gmail"
          }
        ]
      }
    ],
    "citations": [
      {
        "id": "…",
        "context": "…",
        "url": "https://example.com/source",
        "title": "Source title",
        "source": "gmail"
      }
    ],
    "followup_questions": ["What specific area of AI interests you?"],
    "answer_quality": "HIGH",
    "citation_status": "SUCCESS"
  }
}

Citations may use url (public sources) or deeplink (the user's connected Needl-indexed sources such as emails or files). Reuse session_id on the next call to continue the conversation.

2. who_am_i

Get the current user's profile — name, email, and user identifier.

Description: Returns the authenticated user's identity. Useful for showing the user which account they're connected as, or for personalizing follow-up prompts.

Parameters: (none)

Response:

The user profile is returned under a claims key, with the user record under results.

{
  "claims": {
    "results": {
      "username": "Jane Doe",
      "email_id": "[email protected]",
      "public_uuid": "p-abc-123"
    }
  }
}

3. list_integrations

List the user's integrations (also called apps, sources, connectors, connections, linked accounts, or data sources) and their connection status.

Description: Returns each integration categorized as connected, needs_reconnect, or not_connected, with counts per category. Useful when the user asks "what's connected?" or "is my Gmail linked?". To actually search inside an integration's content (emails, messages, files), use ask_needl — list_integrations only reports setup status.

Parameters: (none)

Response:

source_id mirrors the backend label (gmail, slack, teams, outlook, googledrive, onedrive, dropbox, sharepoint, box, onenote, twitter, telegram, …).
status is one of connected, needs_reconnect, not_connected.

{
  "integrations": [
    { "source_id": "gmail", "name": "Gmail",           "status": "connected" },
    { "source_id": "slack", "name": "Slack",           "status": "needs_reconnect" },
    { "source_id": "teams", "name": "Microsoft Teams", "status": "not_connected" }
  ],
  "counts": { "connected": 1, "needs_reconnect": 1, "not_connected": 1 }
}

4. get_integration_accounts

Get the connected accounts under a specific integration — e.g. which Gmail mailbox, which Slack workspace, which OneDrive identity.

Description: Drill into one integration after list_integrations. Returns each account with its account_id (email / workspace id / handle), verifiable_id_type, status, and connection timestamp.

Parameters:

source (string, required): The integration source_id from list_integrations (e.g. gmail, slack, teams, outlook, googledrive, onedrive, dropbox, sharepoint).

Response:

account_id is the integration-native identifier — typically an email for mail providers (gmail, outlook), a team id for Slack, a workspace handle, etc.
verifiable_id_type describes the kind of identifier (e.g. email, team_id).
status is active or needs_reconnect.
created_at is an ISO 8601 timestamp.

{
  "source_id": "gmail",
  "accounts": [
    {
      "account_id": "[email protected]",
      "verifiable_id_type": "email",
      "status": "active",
      "created_at": "2021-12-20T11:33:20+00:00"
    },
    {
      "account_id": "[email protected]",
      "verifiable_id_type": "email",
      "status": "needs_reconnect",
      "created_at": "2021-12-21T15:20:00+00:00"
    }
  ]
}

Authentication

The Needl MCP server requires OAuth 2.0 with PKCE for every MCP request (calls to /mcp). There is no API-key mode — MCP calls must carry a valid Bearer access token.

How it works in practice

You add the server URL to your MCP client (Claude Desktop, ChatGPT, Cursor, etc.).
On the first MCP call, the server returns 401 with a WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource" header. The client follows that pointer to discover the authorization server, then completes a standard OAuth 2.0 authorization-code flow with PKCE.
The client opens a browser, the user signs in to Needl, and consents to the requested scopes.
The client receives an access token, stores it, and attaches it to every MCP request as Authorization: Bearer <token>.
The token is automatically refreshed by the client.

Modern MCP clients handle steps 2–5 transparently — there is nothing to configure manually.

Setup Instructions

Claude Desktop

Add the following to your Claude Desktop config:

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "needl": {
      "url": "https://mcp.needl.ai/mcp"
    }
  }
}

Restart Claude Desktop. The first tool call will open a browser window to sign in to Needl.

ChatGPT (Developer Mode connectors)

Add a new MCP connector and point it at https://mcp.needl.ai/mcp. ChatGPT handles the OAuth handshake automatically.

Cursor

Add an MCP server entry pointing at https://mcp.needl.ai/mcp in Cursor's MCP settings. OAuth is initiated on the first call.

Other MCP clients

Any client that speaks Streamable HTTP MCP and supports OAuth 2.0 / PKCE for protected resources will work. Point it at https://mcp.needl.ai/mcp — the client will discover everything else from the .well-known endpoints.

Best Practices

Query Formulation

Be specific: Provide clear, focused questions with enough context.
- Good: "What was Apple's R&D spend in fiscal 2024?"
- Poor: "Apple R&D"
Keep questions concise: 1–2 sentences works best.
Use natural language: Phrase queries as questions rather than keyword searches.
Mix sources freely: A single ask_needl call can pull from both your private data and public filings — e.g. "Summarize my recent emails with Acme Corp and their last 10-Q."

Session continuity

Generate a fresh UUID v4 session_id at the start of a new conversation.
Reuse the same session_id on every follow-up to preserve context. The model uses the prior turns to interpret pronouns ("their revenue"), comparisons ("vs last year"), and refinements ("filter to just Q3").
Start a new session_id when the user clearly changes topics.

When to enable `web_search`

Set web_search: true only when the question needs live public web content that Needl's indexed sources won't have — breaking news, very recent product launches, trends in last week's headlines, etc.
Leave it false (the default) for financials, filings, capital markets, and anything in the user's connected data — it's faster and uses authoritative sources.

Picking the right tool

ask_needl — any question over data (financials, filings, markets, the user's own files / emails / messages).
list_integrations and get_integration_accounts — only when the user asks about their setup ("which apps are connected?", "what mailboxes do I have linked?"). Do not call these to search inside an integration's content.
who_am_i — when the user asks about their own account, or you need to surface who they're signed in as.

Data Coverage

Capital markets and regulatory filings

Region	Source	Document types
India	BSE, NSE	Annual reports, quarterly results, board resolutions, shareholding patterns, corporate announcements
US	SEC / EDGAR	10-K, 10-Q, 8-K, proxy statements, earnings call transcripts, investor presentations
New Zealand	NZX	Annual reports, interim reports, continuous disclosure notices, substantial security holder notices

Updated in near-real-time as filings are made public.

User's connected data sources

When the user has linked them, ask_needl can also search:

Gmail, Outlook (email)
Slack, Microsoft Teams (messages)
Google Drive, OneDrive, Dropbox, SharePoint, Box (documents and files)
Notes apps (OneNote, Evernote)
…and other sources available in the Needl app.

Use list_integrations to see what's connected for the current user.

Troubleshooting

401 Unauthorized

Cause: Missing, expired, or invalid access token.

Fix:

In your MCP client, sign out and reconnect to Needl so a fresh token is issued.
Confirm the user's Needl account is active.
For programmatic clients, verify the Authorization: Bearer <token> header is being sent on every request.

Tool not found

Cause: Client cached an older tool list, or the tool name was mistyped.

Fix:

Restart your MCP client.
Confirm the tool name (case-sensitive): ask_needl, who_am_i, list_integrations, get_integration_accounts.

Empty or unexpected results

Fix:

Rephrase the question with more specifics (company, time period, metric).
Reuse the same session_id so follow-ups have prior context.
If you expected results from your own data, check list_integrations — the relevant app may not be connected or may need to be reconnected.

Connection issues

Fix:

Verify the URL: https://mcp.needl.ai/mcp.
Check for firewalls or proxies blocking the OAuth redirect.

Privacy & Data Usage

Every request is authenticated as a specific Needl user; tools only return data that user is authorized to see.
The server does not store user credentials — only short-lived OAuth tokens.
Queries may be logged for service improvement and abuse monitoring.
Public data is sourced from official filings and the public web.

For more details, see our Privacy Policy.

Support

Email: oneteam@needl.ai
Documentation: https://api.needl.ai/docs/askneedl-mcp-server

Version History

Version 2.0.0 (June 2026)

Consolidated the four region-scoped tools (ask_needl_web, ask_india_capital_markets, ask_us_capital_markets, ask_nz_capital_markets) into a single ask_needl tool that covers public market data and the user's connected private data in one call.
Added who_am_i, list_integrations, and get_integration_accounts.
Introduced session continuity via session_id.
Added optional web_search parameter on ask_needl.
OAuth 2.0 with PKCE is now required on all MCP calls. The previous unauthenticated mode is no longer available on the public endpoint.

Version 1.0.0 (January 2026)

Initial release.
Four region-scoped tools, HTTP MCP, no authentication.

License

Usage is subject to our Terms of Service and Privacy Policy.

Needl MCP Server

Overview

Available Tools

1. ask_needl

2. who_am_i

3. list_integrations

4. get_integration_accounts

Authentication

How it works in practice

Setup Instructions

Claude Desktop

ChatGPT (Developer Mode connectors)

Cursor

Other MCP clients

Best Practices

Query Formulation

Session continuity

When to enable web_search

Picking the right tool

Data Coverage

Capital markets and regulatory filings

User's connected data sources

Troubleshooting

401 Unauthorized

Tool not found

Empty or unexpected results

Connection issues

Privacy & Data Usage

Support

Version History

Version 2.0.0 (June 2026)

Version 1.0.0 (January 2026)

License

When to enable `web_search`