Connect your AI agent

GitDB hosts an MCP server for your repositories. Any agent that can talk to a remote MCP server connects to it directly, with nothing to install: you give it the server URL, your personal access token, and the repository to work on.

Before you startCopy Anchor Link

You need:

• A gitdb.co account with access to at least one repository.
• A personal access token (step 1 below).
• An MCP client, such as Claude Code, Cursor, or Windsurf.

Connection detailsCopy Anchor Link

Each connection works on one repository. GitDB's tools don't take a repository argument, so the connection itself names the repository:

• If your account can access more than one repository, X-Gitdb-Repo is required.
• If your account can access exactly one repository, it's optional. Setting it anyway keeps the connection working after you gain access to a second repository.
• To work with several repositories, add one server entry per repository, each with its own name and its own X-Gitdb-Repo value.

If your client can't send custom headers other than Authorization, add the repository to the URL instead: https://mcp.gitdb.co/mcp?repo=org/repo. Use one method or the other. If the header and the URL name different repositories, the connection is refused.

Step 1: Create a personal access tokenCopy Anchor Link

1. Sign in at gitdb.co and open Settings → Personal access tokens (gitdb.co/settings/tokens).
2. Click Generate new token.
3. Give the token a name that tells you which agent uses it.
4. Choose scopes:
   • repo:read is enough for the search, read, and history tools.
   • Add repo:write if the agent should create branches or tags, stage and commit changes, merge branches, or save memories. Without a write scope, those tools are refused.
5. Choose an expiration and generate the token.
6. Copy the token right away. You will not be able to see it again. Personal access tokens start with gdb_.

The token acts with your permissions. It can reach the repositories your account can reach, and it can write only where your organization role allows writing. Treat it like a password. If it's ever exposed, revoke it on the same settings page and generate a new one.

The examples below read the token from an environment variable named GITDB_TOKEN, so the token never appears in a config file. To set it for your current terminal session on macOS or Linux, run this and paste the token when prompted (nothing is echoed):

read -rs GITDB_TOKEN && export GITDB_TOKEN

The variable must be visible to the program that runs your agent. You can also paste the token in place of the variable reference in a config file. If you do, keep that file out of version control.

Step 2: Add GitDB to your agentCopy Anchor Link

In every example, replace acme/web-app with your own organization and repository.

Claude CodeCopy Anchor Link

Add the server from your project directory:

claude mcp add --transport http gitdb https://mcp.gitdb.co/mcp \
  --header "Authorization: Bearer $GITDB_TOKEN" \
  --header "X-Gitdb-Repo: acme/web-app"

Your shell fills in the token when you run the command. Claude Code saves the server for the current project.

To share the setup with your team, commit a .mcp.json file to the project root instead. Each teammate then sets their own GITDB_TOKEN:

{
  "mcpServers": {
    "gitdb": {
      "type": "http",
      "url": "https://mcp.gitdb.co/mcp",
      "headers": {
        "Authorization": "Bearer ${GITDB_TOKEN}",
        "X-Gitdb-Repo": "acme/web-app"
      }
    }
  }
}

CursorCopy Anchor Link

Add the server to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json in a project root to use it in that project only:

{
  "mcpServers": {
    "gitdb": {
      "url": "https://mcp.gitdb.co/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GITDB_TOKEN}",
        "X-Gitdb-Repo": "acme/web-app"
      }
    }
  }
}

Windsurf (now Devin Desktop)Copy Anchor Link

Open the MCP config file from the Cascade panel: click the ... (Actions) menu at the top right, then click Open MCP config file in the MCPs section. On macOS and Linux the file is ~/.config/devin/mcp_config.json; on Windows it's %APPDATA%\devin\mcp_config.json. Add:

{
  "mcpServers": {
    "gitdb": {
      "serverUrl": "https://mcp.gitdb.co/mcp",
      "headers": {
        "Authorization": "Bearer ${env:GITDB_TOKEN}",
        "X-Gitdb-Repo": "acme/web-app"
      }
    }
  }
}

Windsurf names the URL field serverUrl, not url.

Other MCP clientsCopy Anchor Link

Any client that supports remote MCP servers over Streamable HTTP with custom request headers can connect using the connection details above.

Step 3: Verify the connectionCopy Anchor Link

1. Confirm that your client sees the server:
   • Claude Code: run /mcp in a session. gitdb should show as connected.
   • Cursor: in Cursor's MCP settings, check that gitdb is enabled and lists its tools.
   • Windsurf: in the MCPs section of the Cascade panel, check that gitdb is listed.
2. Ask your agent: "List the branches and tags in this repository."

The agent calls gitdb_list_refs and replies with your repository's branches and tags. That confirms your token, your repository selection, and your allowance all work. The check itself uses one tool call. See MCP tools for everything your agent can do.

Daily tool-call allowanceCopy Anchor Link

• Each tool call your agent makes counts as one call against the daily allowance of the organization that owns the connected repository.
• Connecting, reconnecting, and listing the available tools don't count.
• A tool refused because your plan doesn't include its feature (such as semantic search or agent memory) doesn't count either.
• The allowance resets at 00:00 UTC. How many calls you get per day depends on your plan; see gitdb.co/pricing.
• When the allowance runs out, the connection stays open. Each tool returns a message saying the organization's daily MCP quota was exceeded and the tool was not executed. Tools work again after 00:00 UTC, or after you upgrade to a plan with a larger allowance.
• For repositories owned by your personal account, you can track usage on the MCP tool calls today card on your dashboard, on Settings → Billing & plans, and in the footer of every gitdb.co page.

TroubleshootingCopy Anchor Link

GitDB answers failed requests with one of the messages below. Depending on the client, you'll see it in the agent's reply or in the client's MCP logs.