> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neo.projectdiscovery.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Neo to Cursor, Claude, and any MCP-compatible client over the Model Context Protocol so you can run security tasks, monitor results, and pull files from wherever you already work.

Neo ships a hosted **Model Context Protocol (MCP)** server. MCP is an open standard that lets AI assistants discover and call external tools. Point any MCP-compatible client — Cursor, Claude, or your own agent — at Neo's endpoint and it gains a set of tools for starting security assessments, monitoring them, reading validated findings, and pulling the files Neo generates.

This is the simplest way to drive Neo from outside the web app: no SDK to install, no API wrapper to build. You add one endpoint and your API key, and the client does the rest.

<Info>
  This is the **inbound** direction — external clients calling Neo. If you instead want Neo's agents to call *your* MCP servers as tools during a task, see [MCP Tools](/platform/tools/mcp-tools).
</Info>

## Prerequisites

* A Neo API key (prefix `neo_sk_`), created under **Settings → API Key** (see [API Key](/platform/settings/api-key)).
* An MCP-compatible client — Cursor, Claude Code, Claude Desktop, or any client that supports streamable HTTP.

<Warning>
  Your API key carries the same permissions as your account. Treat it like a password: store it in your client's secret/header configuration, never commit it to source control, and rotate it if it leaks.
</Warning>

## Connection details

Use these values in any MCP client that supports a remote HTTP server.

| Setting            | Value                                 |
| :----------------- | :------------------------------------ |
| **Endpoint URL**   | `https://mcp.projectdiscovery.io/mcp` |
| **Transport**      | Streamable HTTP (HTTP `POST` + SSE)   |
| **Authentication** | `X-Api-Key: neo_sk_your_key_here`     |

## Connect your client

<Tabs>
  <Tab title="Cursor">
    Add Neo to your Cursor MCP configuration (`~/.cursor/mcp.json` for all projects, or `.cursor/mcp.json` inside a project):

    ```json theme={"system"}
    {
      "mcpServers": {
        "neo": {
          "url": "https://mcp.projectdiscovery.io/mcp",
          "headers": {
            "X-Api-Key": "neo_sk_your_key_here"
          }
        }
      }
    }
    ```

    Reload Cursor, then open **Settings → MCP** and confirm the **neo** server shows a green status with its tools listed.
  </Tab>

  <Tab title="Claude Code">
    Add the server from your terminal with the CLI:

    ```bash theme={"system"}
    claude mcp add --transport http neo https://mcp.projectdiscovery.io/mcp \
      --header "X-Api-Key: neo_sk_your_key_here"
    ```

    Verify it connected:

    ```bash theme={"system"}
    claude mcp list
    ```

    Inside a session, run `/mcp` to see Neo's tools and resources.
  </Tab>

  <Tab title="Claude Desktop">
    In **Settings → Connectors → Add custom connector**, set the remote MCP URL to:

    ```
    https://mcp.projectdiscovery.io/mcp
    ```

    When prompted for authentication, add a header `X-Api-Key` with your `neo_sk_` key. Save, then open a new chat — Neo's tools appear under the connectors menu.
  </Tab>

  <Tab title="Any MCP client">
    Configure a **remote / streamable HTTP** server with:

    * **URL**: `https://mcp.projectdiscovery.io/mcp`
    * **Header**: `X-Api-Key: neo_sk_your_key_here`

    Any client that implements the MCP streamable HTTP transport (custom agents, IDE plugins, the MCP Inspector, etc.) can connect the same way. After connecting, call `tools/list` to discover the tools described below.
  </Tab>
</Tabs>

## Authentication

Authentication uses your Neo **API key** only. Send it with every request in the `X-Api-Key` header:

```
X-Api-Key: neo_sk_your_key_here
```

The key must have the `neo_sk_` prefix and is created under **Settings → API Key** ([API Key](/platform/settings/api-key)). If it's missing or invalid, requests fail with an authentication error. Keep the key in your client's header config — never in the URL.

## Available tools

Once connected, your client gets a set of tools that follow the natural loop of an assessment — start it, watch it, read the findings, and pull the files.

| Tool                | What it does                                                                                                                  |
| :------------------ | :---------------------------------------------------------------------------------------------------------------------------- |
| `create_task`       | Start a new assessment (pentest, code review, recon, CVE triage, and more), or continue an existing one. Returns a `task_id`. |
| `get_task`          | Check a task: its status, logs, report, or files — pick a `view`.                                                             |
| `get_issues`        | List validated findings, each with severity, target, and remediation.                                                         |
| `list_tasks`        | Browse your past assessments, with optional filters.                                                                          |
| `list_capabilities` | See the agents, models, and projects you can target.                                                                          |
| `manage_task`       | Rename a task, stop a running one, or delete it for good.                                                                     |
| `get_file`          | Fetch a file a task produced — inline, or as a download link.                                                                 |

### get\_task views

`get_task` takes a `task_id` and an optional `view` (defaults to `overview`). Each view returns a different slice of the task.

| View       | Returns                                                                                                                                                          |
| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `overview` | Status, title, and the assistant's latest response. The quickest way to check where a task stands.                                                               |
| `logs`     | The agent and tool execution audit log — each step Neo took, with targets and outcomes.                                                                          |
| `report`   | The narrative Insights summary. Generated on demand once the task finishes; if the task is still running, the view says so and you can retry after it completes. |
| `files`    | The artifacts the task produced (reports, screenshots, scan output), with the `file_key` for each.                                                               |

<Tip>
  For the concrete list of validated vulnerabilities, use `get_issues` (scope it with `task_id`) rather than a `get_task` view — findings are first-class objects with severity and remediation.
</Tip>

### create\_task parameters

`create_task` is the main entry point. Only `task` is required; everything else has a sensible default.

| Parameter    | Required | Default | Description                                                                                                                                                                             |
| :----------- | :------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `task`       | Yes      | —       | The objective for Neo, e.g. `"Run a security review of https://staging.example.com"`.                                                                                                   |
| `model`      | No       | `auto`  | The model that runs the task. `auto` lets Neo pick the best model per step; or name one from `list_capabilities`. See [Models](/platform/settings/models); access depends on your plan. |
| `mode`       | No       | `agent` | `agent` for autonomous multi-step work, or `chat` for a lighter conversational response.                                                                                                |
| `agent_id`   | No       | —       | Route the task to a specific [agent](/platform/agents) (see `list_capabilities`).                                                                                                       |
| `project_id` | No       | —       | Scope the task to a project (see `list_capabilities`).                                                                                                                                  |
| `task_id`    | No       | —       | An existing task's UUID — pass it to continue that conversation instead of starting a new one.                                                                                          |

<Note>
  `create_task` returns as soon as the task is created and queued; Neo keeps working in the background. Use `get_task` with the returned task ID to follow progress, then `get_issues` to read the findings. Neo tasks run for minutes — avoid polling in a tight loop.
</Note>

## Resources

Resources let clients browse Neo data without invoking a tool. They return JSON.

| URI                     | Description                                    |
| :---------------------- | :--------------------------------------------- |
| `neo://tasks`           | The list of your most recent tasks (up to 50). |
| `neo://tasks/{task_id}` | A single task with its full message history.   |

## Example workflow

A typical end-to-end loop from an MCP client:

<Steps>
  <Step title="Start a task">
    Call `create_task` with `task: "Test https://staging.example.com for authentication and authorization flaws"`. Note the returned `task_id`. (Optionally call `list_capabilities` first to pick a specific agent, model, or project.)
  </Step>

  <Step title="Monitor progress">
    Call `get_task` with the `task_id` and `view: "overview"` to check status and the latest response, or `view: "logs"` to follow each step. Neo tasks run for minutes, so check periodically rather than in a tight loop.
  </Step>

  <Step title="Read the findings">
    Call `get_issues` with `task_id` to list the validated findings — each with severity, target, and remediation. Use `get_task` with `view: "report"` for the narrative summary.
  </Step>

  <Step title="Collect artifacts">
    Call `get_task` with `view: "files"` to find generated reports or screenshots, then pass a returned `file_key` to `get_file` to read it inline or get a shareable download link.
  </Step>

  <Step title="Wrap up">
    Use `manage_task` with `action: "rename"` for easy lookup later, or `action: "delete"` if it was a throwaway run.
  </Step>
</Steps>

## File keys

`get_file` operates on **file keys** — the full workspace path of a file, always starting with `workspace/`. Task artifacts live under `workspace/tasks/{task_id}/`. A typical key looks like:

```
workspace/tasks/8c1a9f4e-2b6d-4f3a-9b2c-1e7d5a0c4f21/report.pdf
```

`get_task` with `view: "files"` returns the exact key for every file, so the usual pattern is to list first, then pass a returned key to `get_file`.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The client connects but shows no tools">
    Make sure the URL ends in `/mcp` and your client is configured for the **streamable HTTP** transport. After fixing the config, fully reload the client so it re-runs MCP discovery.
  </Accordion>

  <Accordion title="Every call returns an authentication error">
    Confirm the `X-Api-Key` header is set and the value starts with `neo_sk_`. Keys created in the wrong team, revoked, or rotated will fail — generate a fresh one under **Settings → API Key** and update your client.
  </Accordion>

  <Accordion title="File tools say the sandbox isn't available">
    Workspace files are created during task execution. Run at least one task first so your workspace is initialized, then retry `get_task` with `view: "files"`.
  </Accordion>

  <Accordion title="create_task times out">
    `create_task` waits for the task to be registered before returning. A timeout usually means the upstream Neo API or agent is briefly unavailable — retry, and check your account has sufficient credits and Neo access.
  </Accordion>
</AccordionGroup>

## Security notes

* **Stateless by design.** The MCP server holds no credentials or sessions; your key is used only to authenticate the current request to the Neo API.
* **Scoped to your account.** Tools only ever act on tasks and files your API key can access.
* **HTTPS only.** Always connect over `https://`, and keep your key in headers rather than URLs.