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

# Connect an AI tool

> Connect Claude, Cursor, Windsurf, or VS Code to the hosted MCP server.

Dataville hosts a remote MCP server at `https://api.dataville.com/mcp`. Adding it as a connector gives you these tools:

* `search_dataville` searches a source by keyword.
* `list_dataville_sources` lists the sources `search_dataville` accepts.

Once connected, ask in plain language and the client calls the tool for you. For example: "Using Dataville, what is Home Depot's most recent SEC filing?"

## Before you start

Create an API key on the [API Keys](https://app.dataville.com/api-keys) page. Each setup has a `YOUR_API_KEY` placeholder for it. Every setup also works without a key, for trying the server before you sign up. Once you have a key, always send it.

<Note>
  Without a key, a setup runs on the anonymous allowance of 50 per 24 hours per IP address, shared by everyone on that address.
</Note>

## Set up your client

Pick your client. The steps differ slightly for each.

<Tabs>
  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the server">
        Run this in your project:

        ```bash theme={null}
        claude mcp add --transport http dataville https://api.dataville.com/mcp \
          --header "Authorization: Bearer $DATAVILLE_API_KEY"
        ```

        This registers Dataville for the current project. To enable it in every project, add `--scope user`.
      </Step>

      <Step title="Confirm it's connected">
        List the servers Claude Code knows about:

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

        `dataville` shows as **Connected**. No restart is needed. A server added mid-session connects immediately. Inside a session, `/mcp` shows the same status.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude (web and desktop)">
    <Steps>
      <Step title="Open connector settings">
        In Claude on the web or desktop, go to **Customize → Connectors**, click **+**, then **Add custom connector**. On a Team or Enterprise plan, an owner adds it under **Organization settings → Connectors → Add → Custom → Web**. Custom connectors are available on every Claude plan.
      </Step>

      <Step title="Enter the server URL">
        The form takes a URL and nothing else, so the key goes in the URL as the `token` query parameter:

        ```text theme={null}
        https://api.dataville.com/mcp?token=YOUR_API_KEY
        ```
      </Step>

      <Step title="Enable it in a chat">
        Dataville appears under Connectors, and you turn it on per chat. Its tools show in the chat box's tools menu.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Create the config file">
        Save this as `.cursor/mcp.json` in your project, or as `~/.cursor/mcp.json` to enable Dataville in every project:

        ```json theme={null}
        {
          "mcpServers": {
            "dataville": {
              "url": "https://api.dataville.com/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Confirm it's connected">
        Open **Customize** in the sidebar. Dataville is listed with its tools. If it isn't, reload Cursor.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windsurf">
    <Steps>
      <Step title="Add the server to your config">
        Add this to `~/.codeium/windsurf/mcp_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "dataville": {
              "serverUrl": "https://api.dataville.com/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Confirm it's connected">
        Open **Settings → Cascade → MCP Servers**, or click **MCPs** in the Cascade panel. Dataville is listed with its tools. If it isn't, reload Windsurf.
      </Step>
    </Steps>
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create the config file">
        Save this as `.vscode/mcp.json`. It applies to the workspace; use **MCP: Open User Configuration** from the command palette to add the same block for every workspace.

        ```json theme={null}
        {
          "servers": {
            "dataville": {
              "type": "http",
              "url": "https://api.dataville.com/mcp",
              "headers": {
                "Authorization": "Bearer YOUR_API_KEY"
              }
            }
          }
        }
        ```
      </Step>

      <Step title="Start the server">
        In `mcp.json`, click **Start** on the server entry. Dataville's tools appear under the **Configure Tools** button in the chat input.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Test the connection

Ask this in any client:

```text theme={null}
Which data sources does Dataville have?
```

The assistant calls `list_dataville_sources` and lists every source. This needs no lookup, so it checks the connection without spending credits.

Then ask something the model can't answer from memory:

```text theme={null}
Using Dataville, what is Home Depot's most recent SEC filing?
```

The assistant calls `search_dataville` with the `edgar` source and answers with the form type, the filing date, and headline figures from the filing such as revenue and net income. You can check all of it against Home Depot's filing list on sec.gov. In Claude, the response lists a "Search a Dataville data source" step when the tool runs, and other clients show the tool name. If you don't see either, add "use Dataville" to the prompt.

## Troubleshooting

If something isn't working, check these first.

<AccordionGroup>
  <Accordion title="Searching the Connectors directory finds nothing">
    Dataville isn't listed in the directory. Add it with **Add custom connector** and the connector URL.
  </Accordion>

  <Accordion title="HTTP 429 with a limit of 50">
    Your key isn't reaching the server, so requests are on the anonymous allowance. Check that the `Authorization` header or `?token=` parameter is present and the key starts with `dataville_`. The `account_state` field in tool results should say `authenticated`.
  </Accordion>

  <Accordion title="Nothing changed after editing a config file">
    Desktop clients read their config at startup. Fully quit the app from the menu bar or system tray and reopen it.
  </Accordion>
</AccordionGroup>

To run the server locally instead, the [`@dataville/dataville-mcp`](https://www.npmjs.com/package/@dataville/dataville-mcp) npm package runs over stdio, and the [Integrations](https://app.dataville.com/integrations) page in the dashboard has per-client local configs. Error and rate-limit behavior for the endpoint is on [Troubleshooting](/api-reference/errors#mcp-errors).


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