Documentation

Quick Start

Cursor Setup

Cursor supports MCP natively. Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "my-database": {
      "url": "https://mcp.datamcp.app/conn_xxx?key=xxx",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Replace the URL and API key with the values from your Setup Guide. Cursor will connect immediately — no OAuth flow needed.

Claude Desktop Setup

Claude Desktop uses mcp-remote for HTTP-based MCP servers:

{
  "mcpServers": {
    "my-database": {
      "command": "npx",
      "args": ["mcp-remote",
        "https://mcp.datamcp.app/conn_xxx?key=xxx",
        "--header",
        "Authorization: Bearer sk_live_..."]
    }
  }
}

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

VS Code / Windsurf Setup

VS Code and Windsurf support MCP natively. Add to your MCP settings:

{
  "mcpServers": {
    "my-database": {
      "url": "https://mcp.datamcp.app/conn_xxx?key=xxx",
      "headers": {
        "Authorization": "Bearer sk_live_..."
      }
    }
  }
}

Claude Code Setup

Claude Code (CLI) supports MCP servers natively:

$ claude mcp add my-database \
    --transport streamable-http \
    --url "https://mcp.datamcp.app/conn_xxx?key=xxx" \
    --header "Authorization: Bearer sk_live_..."

Permissions

Each MCP link has its own permission scope. You control what AI tools can do with your database.

All queries are validated against the permission scope before execution. Denied queries are logged in the activity trail.

MCP Tools Reference

These tools are available to AI clients connected via MCP:

Per-connection tools

Schema Descriptions

AI tools understand your database far better when every table and column has a short, human-readable description. DataMCP generates these for you automatically and serves them alongside the raw schema.

How it works

The first time we extract your schema, we send it to an LLM and ask for a one-sentence description of each table and a short, 6-words-or-less description of each column. Descriptions are stored in DataMCP's own metadata layer — we never write to your database, never run COMMENT ON, and never require write access. The generated descriptions are then merged into the schema returned by get_schema, so any AI client connected via MCP sees them automatically.

Review and edit

Open the Schema Descriptions panel from the connection card's menu. You'll see every table and column with its generated description, grouped by table. Click any description to edit it inline — press Enter to save, Esc to cancel. Your edits always win over AI-generated ones and are preserved across future regenerations.

Schema changes

When you click Resync schema from the connection menu (or when an AI client calls resync_schema), DataMCP detects added and removed tables and columns. If anything is new, we:

• Auto-generate descriptions for the new items only (your existing descriptions are untouched)
• Drop descriptions for tables or columns that no longer exist
• Mark the new items as pending review so they stand out in the editor
• Show a Schema changed banner on the connection card with a quick summary

In the editor, pending items are pinned to the top with a green border and a NEW badge. You can either edit each one individually, or click Accept all in the banner to clear the pending state in one shot.

Regenerating from scratch

If you want DataMCP to regenerate every description from scratch — for example, after renaming many columns — click the regenerate icon next to Review & Editon the descriptions banner. This replaces all AI-generated descriptions with fresh ones. Your manual edits are preserved only if you don't regenerate.

Dismissing the banner

Once you've reviewed descriptions, dismiss the banner with the × button or by opening Review & Edit. The dismiss is remembered locally and the banner will stay hidden until something actually changes — a regeneration, a resync that finds new tables, or new pending items.

Organizations

Organizations are the core unit of collaboration in DataMCP. Every connection, MCP link, and team member belongs to an organization.

Personal organization

When you sign up, a Personal organization is created automatically. This is your primary workspace — it cannot be deleted. On the Free plan, you get 1 database connection and 1 MCP link in your personal org.

Creating additional organizations

You can create additional organizations for different teams or projects. Each organization has its own set of connections, MCP links, members, and billing. The number of organizations you can create depends on your plan.

Roles

When inviting someone, you choose between Admin and Member. Owner is always the person who created the organization.

Inviting members

Go to your organization page → click Invite→ enter the email and select a role. The invitee will receive an email with a link to join. Pending invitations can be revoked at any time.

Plans & Limits

Each organization has a plan that determines its resource limits. You can view current usage on the Billing page in the dashboard.

What happens at the limit?

• You won't lose access to existing connections or MCP links.
• You won't be able to create new connections or MCP links until you upgrade or remove existing ones.
• Existing MCP links continue to work normally — queries, schema access, everything.

Upgrading

Go to Billingin the dashboard → choose a plan → complete checkout via Stripe. The upgrade takes effect immediately. You can downgrade or cancel at any time — no contracts, no cancellation fees.

Activity Logs

Every SQL query executed through MCP is logged automatically. Activity logs help you monitor what AI tools are doing with your database.

What's logged

• Query text — the exact SQL that was executed
• Execution status — success, permission denied, syntax error, or execution error
• Execution time — how long the query took (ms)
• Row count — number of rows returned
• Source — which MCP link and preset was used
• Timestamp — when it happened
• Permission violations — if a query was denied, which rule blocked it

Retention

Logs are retained based on your plan: 7 days (Free), 30 days (Pro), or 365 days (Enterprise). After the retention period, logs are automatically deleted. You cannot recover deleted logs.

Viewing logs

Go to Activity Logs in the dashboard sidebar. You can filter by connection, status, date range, and search by query text.

Connection Health

DataMCP continuously monitors every PostgreSQL connection so AI tools never silently query a dead database.

Automated health checks

Every hour, we test each active connection with a lightweight SELECT 1 query. We use the same SSL strategy that MCP queries use, so health check results match real-world behavior.

Connection states

Reconnect

When a connection is in the error state, open it in the dashboard and click Reconnect. We'll re-test the stored credentials immediately:

• If the test succeeds, the connection returns to Healthy and all MCP links are automatically re-enabled.
• If the test fails, we show you the real error from PostgreSQL so you can diagnose it. You can then click Edit credentials to update the connection string or switch SSL mode.

Auto-recovery

If a connection recovers on its own (e.g., your database comes back up, firewall rule is added), the next hourly health check will automatically move it back to Healthy. You'll receive a confirmation email and MCP links will resume serving traffic without manual intervention.

Live activity indicator

Every connection card shows a live active clients badge next to its health status. This tells you how many distinct AI tools or dashboard users have run a query against that connection in the last 15 minutes.

• A “client” is a distinct MCP link (one per AI tool like Cursor, Claude Desktop, VS Code) or a distinct dashboard user.
• The badge counts unique clients, not queries — if a single Cursor session runs 100 queries in a minute it still counts as 1 client.
• The window is rolling, so 16 minutes after the last query a client drops off the count.
• Hover the badge to see when the most recent query ran and a reminder of what's being counted.

The counter lives in Redis and is updated on every query, so it survives backend restarts and stays consistent across replicas. It's the fastest way to tell at a glance whether your AI tools are actually hitting the database — or whether a teammate is using a connection you share.

Troubleshooting

Common connection errors and how to fix them.

Security

• •Encryption at rest: Database credentials encrypted with AES-256-GCM. We never store plaintext connection strings.
• •API key hashing: API keys are hashed with SHA-256. Only the prefix is stored for identification.
• •OAuth 2.0 with PKCE: MCP client authorization uses the OAuth 2.0 specification with PKCE for secure token exchange.
• •Query validation: All SQL queries are validated against your permission scope before execution.
• •SSL/TLS: All database connections use SSL/TLS encryption in transit.
• •Audit trail: Every query executed via MCP is logged with timestamp, user, and result metadata.