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

# MCP Servers (Beta)

## Overview

We provide two MCP servers:

* [REST APIs MCP Server](#rest-apis-mcp-server): Allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc.
* [Docs MCP Server](#docs-mcp-server): Allows you to search and browse Velt's documentation directly within your MCP-compatible IDEs, like Cursor, Windsurf etc. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt.

## Supported MCP Clients

The MCP server is compatible with any client that supports MCP. Here are few examples:

* [Cursor](https://www.cursor.com/)
* [Windsurf](https://windsurf.dev/)
* [Claude Desktop](https://www.anthropic.com/products/claude-desktop)

## REST APIs MCP Server

This allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc.

### Tools

The MCP server exposes **all** the [Velt REST APIs](/api-reference/rest-apis/v2/workspace/create) as tools.
Below you will find links to different collections of APIs:

* [Organizations](/api-reference/rest-apis/v2/organizations/add-organizations)
* [Folders](/api-reference/rest-apis/v2/folders/add-folder)
* [Documents](/api-reference/rest-apis/v2/documents/get-documents-v2)
* [Users](/api-reference/rest-apis/v2/users/get-users-v2)
* [User Groups](/api-reference/rest-apis/v2/user-groups/add-groups)
* [Comments](/api-reference/rest-apis/v2/comments-feature/comments/get-comments)
* [Notifications](/api-reference/rest-apis/v2/notifications/get-notifications-v2)
* [Live State](/api-reference/rest-apis/v2/livestate/broadcast-event)
* [Workspace](/api-reference/rest-apis/v2/workspace/add-domain)

### Setup

You can set up the REST API MCP Server using any of the following methods. Note you will be required to provide your Velt API key and Velt Auth token to the MCP server.

#### Using Smithery CLI

The easiest way to get started is by using the `@smithery/cli` package installer. This will automatically download and configure the MCP server for your chosen client.
You can visit: [https://smithery.ai/server/@velt-js/velt-api-mcp](https://smithery.ai/server/@velt-js/velt-api-mcp) to see the list of clients supported by the MCP server and steps to install it. Here are some examples:

<Tabs>
  <Tab title="Claude Desktop">
    ```bash theme={null}
    npx -y @smithery/cli install @velt-js/velt-api-mcp --client claude
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    npx -y @smithery/cli install @velt-js/velt-api-mcp --client cursor
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    npx -y @smithery/cli install @velt-js/velt-api-mcp --client windsurf
    ```
  </Tab>

  <Tab title="Cline">
    ```bash theme={null}
    npx -y @smithery/cli install @velt-js/velt-api-mcp --client cline
    ```
  </Tab>

  <Tab title="VSCode">
    ```bash theme={null}
    npx -y @smithery/cli install @velt-js/velt-api-mcp --client vscode
    ```
  </Tab>
</Tabs>

#### Manual Configuration

If you prefer to configure the server manually, follow these steps.

1. **Install the Server Package:**

```bash theme={null}
npm i @veltdev/api-mcp
```

2. **Configure your client:**
   Here are some examples:

<Tabs>
  <Tab title="Claude Desktop">
    1) Open Claude Desktop.

    2) Go to **Settings > Developer > Edit Config**.

    3) Add the following configuration to the `mcpServers` section in your config file. Make sure to replace the placeholder values.

       ```json theme={null}
       {
         "mcpServers": {
           "velt-api-mcp": {
             "command": "node",
             "args": ["<path-to-velt-api-mcp-server-folder>/dist/index.js"],
             "env": {
               "VELT_API_KEY": "<your-velt-api-key>",
               "VELT_AUTH_TOKEN": "<your-velt-auth-token>"
             }
           }
         }
       }
       ```

    4) Save the configuration file.

    5) Restart Claude Desktop. The `velt-api-mcp` server will now be available in the tools menu.
  </Tab>

  <Tab title="Cursor">
    1. Open Cursor.
    2. Go to **Cursor Settings → Tools & Integrations → New MCP Server**.
    3. Add the following configuration, replacing the placeholders with the full path to the server and your Velt secrets.
       ```json theme={null}
       {
         "mcpServers": {
           "velt-api-mcp": {
             "command": "node",
             "args": ["<path-to-velt-api-mcp-server-folder>/dist/index.js"],
             "env": {
               "VELT_API_KEY": "<your-velt-api-key>",
               "VELT_AUTH_TOKEN": "<your-velt-auth-token>"
             }
           }
         }
       }
       ```
    4. Ensure the server is enabled in the MCP List.
  </Tab>

  <Tab title="Windsurf">
    1. Open Windsurf.
    2. Go to **Windsurf Settings → Manage Plugins → View Raw Config**.
    3. Add the following configuration, replacing the placeholders with the full path to the server and your Velt secrets.
       ```json theme={null}
       {
         "mcpServers": {
           "velt-api-mcp": {
             "command": "node",
             "args": ["<path-to-velt-api-mcp-server-folder>/dist/index.js"],
             "env": {
               "VELT_API_KEY": "<your-velt-api-key>",
               "VELT_AUTH_TOKEN": "<your-velt-auth-token>"
             }
           }
         }
       }
       ```
    4. Ensure the server is enabled in the MCP List.
  </Tab>
</Tabs>

### Use cases

Once configured, you can interact with the Velt API through your MCP client. Here are some examples:

1. **Querying Velt Data:**

* How many comments are there in this organization: ORGANIZATION\_ID?
* Provide a list of users in the this organization: ORGANIZATION\_ID.
* Give me a list of all open comments in this organization: ORGANIZATION\_ID.
* Get all notifications for this user: USER\_ID.
* and more...

2. **Adding or updating sample data:**

* Add, update or delete comments in a given document.
* Add notification for a given user.
* and more...

3. **Analysis:**
   If you are using an agentic client like Cursor, you can also ask questions like:

* What are users discussing in comments in this organization: ORGANIZATION\_ID?
* Categorize the comments as bugs, feature requests, questions, etc in this organization: ORGANIZATION\_ID.
* and more...

4. **Debugging:**

* Add a comment using SDK and ask the MCP to fetch the comment.
* Tag a user in a comment using SDK and ask the MCP to fetch the notification for the user.
* and more...

5. **Use it as a tool for your AI Agent:**

* You could review a document (eg: essay, report, etc) and ask the Velt MCP to add comments providing contextual feedback on the document.
* Here is a sample code of using MCP tool in AI agent with Google AI SDK:

```python theme={null}
TARGET_FOLDER_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "")

root_agent = Agent(
    name="AI Comment Agent",
    model="gemini-2.5-flash",
    description="Agent that adds comments for the product",
    instruction="""
    You are a reviewer who will review the text given and add the comment to improve the content
    """,
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='npx',
                args=[
                    "-y",
                    "@veltdev/api-mcp",
                    os.path.abspath(TARGET_FOLDER_PATH),
                ],
                stderr=subprocess.STDOUT, 
                timeout=60,
                env={
                    "VELT_API_KEY": api_key,
                    "VELT_AUTH_TOKEN": auth_token,
                }
            ),
            tool_filter=[
                'get-comment-annotations', 
                'get-comments',
                'add-comments',
                'update-comments',  
                'delete-comments',
                'add-comment-annotations', 
                'update-comment-annotations', 
                'delete-comment-annotations', 
            ]
        )
    ],
)
```

## Docs MCP Server

The Velt Docs MCP Server allows you to search and browse Velt's documentation directly within your MCP-compatible client, like Cursor, Windsurf, Claude Desktop and more. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt.

### Setup

<Tabs>
  <Tab title="Claude">
    To use the Velt Docs MCP server with Claude:

    <Steps>
      <Step title="Add the Velt Docs MCP server to Claude">
        1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
        2. Select **Add custom connector**.
        3. Add the Velt Docs MCP server:

        * Name: `Velt`
        * URL: `https://docs.velt.dev/mcp`

        4. Select **Add**.
      </Step>

      <Step title="Access the MCP server in your chat">
        1. When using Claude, select the attachments button (the plus icon).
        2. Select the Velt Docs MCP server.
        3. Ask Claude a question about Velt.
      </Step>
    </Steps>

    See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
  </Tab>

  <Tab title="Claude Code">
    To use the Velt Docs MCP server with Claude Code, run the following command:

    ```bash theme={null}
    claude mcp add --transport http Velt https://docs.velt.dev/mcp
    ```

    Test the connection by running:

    ```bash theme={null}
    claude mcp list
    ```

    See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
  </Tab>

  <Tab title="Cursor">
    <PreviewButton href="cursor://anysphere.cursor-deeplink/mcp/install?name=velt&config=eyJuYW1lIjoiVmVsdCIsInVybCI6Imh0dHBzOi8vZG9jcy52ZWx0LmRldi9tY3AiLCJoZWFkZXJzIjp7fX0%3D">Install in Cursor</PreviewButton>

    To connect the Velt Docs MCP server to Cursor, follow these steps:

    <Steps>
      <Step title="Open MCP settings">
        1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
        2. Search for "Open MCP settings".
        3. Select **Add custom MCP**. This will open the `mcp.json` file.
      </Step>

      <Step title="Configure the Velt Docs MCP server">
        In `mcp.json`, add:

        ```json theme={null}
        {
          "mcpServers": {
            "Velt": {
              "url": "https://docs.velt.dev/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Test the connection">
        In Cursor's chat, ask "What tools do you have available?" Cursor should show the Velt Docs MCP server as an available tool.
      </Step>
    </Steps>

    See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details.
  </Tab>

  <Tab title="VS Code">
    <PreviewButton href="https://vscode.dev/redirect/mcp/install?name=mintlify&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmintlify.com%2Fdocs%2Fmcp%22%7D">Install in VS Code</PreviewButton>

    To connect the Velt Docs MCP server to VS Code, click the **Install in VS Code** button. Or to manually connect the MCP server, create a `.vscode/mcp.json` file and add:

    ```json theme={null}
    {
      "servers": {
        "Velt": {
          "type": "http",
          "url": "https://docs.velt.dev/mcp"
        }
      }
    }
    ```

    See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
  </Tab>
</Tabs>

### Example Usage

Once the Velt Docs MCP Server is configured, you can use it to search for documentation from your client.

For example, in Cursor, you can use questions like `how to add Velt popover comments?` in the chat to ask questions about Velt.

**Query:**
`how to add Velt popover comments?`

**Result:**
The MCP will return relevant documentation pages and snippets related to adding popover comments, allowing you to quickly access the information you need.

**More examples:**

* `Generate sample data for adding Velt comment annotations via Velt Rest API`