> ## 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.

# REST APIs MCP Server (Beta)

> Interact with your Velt data from Cursor, Windsurf, Claude Desktop, and other MCP-compatible clients via the REST APIs MCP server.

Interact with your Velt data directly from MCP-compatible clients such as Cursor, Windsurf, and Claude Desktop. This server exposes Velt REST APIs as tools.

<Info>
  Looking for documentation search in your editor? See [Velt Docs MCP](/docs/get-started/docs-mcp). For guided SDK install, see [Velt Installation MCP](/docs/get-started/mcp-installer).
</Info>

## 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)

## Tools

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

* [Organizations](/docs/api-reference/rest-apis/v2/organizations/add-organizations)
* [Folders](/docs/api-reference/rest-apis/v2/folders/add-folder)
* [Documents](/docs/api-reference/rest-apis/v2/documents/get-documents-v2)
* [Users](/docs/api-reference/rest-apis/v2/users/get-users-v2)
* [User Groups](/docs/api-reference/rest-apis/v2/user-groups/add-groups)
* [Comments](/docs/api-reference/rest-apis/v2/comments-feature/comments/get-comments)
* [Notifications](/docs/api-reference/rest-apis/v2/notifications/get-notifications-v2)
* [Live State](/docs/api-reference/rest-apis/v2/livestate/broadcast-event)
* [Workspace](/docs/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', 
            ]
        )
    ],
)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.