datamcp

Hosted MCP gateway for PostgreSQL, MySQL, and OpenAPI with scoped links and server-side credentials.

Documentation

Docs / from source to MCP

datamcp documentation.

Setup and reference.

Choose PostgreSQL or MySQL for schema-aware SQL tools, or OpenAPI / Swagger for controlled REST API discovery and calls. This reference covers the complete path from source connection to a hosted MCP link in Cursor, Claude, VS Code, or ChatGPT.

PostgreSQLDatabase schema and SQL toolsConnect PostgreSQL 12+, scope operations per MCP link, keep credentials server-side, and review query activity.MySQLDatabase schema and SQL toolsConnect MySQL, keep credentials server-side, and combine MCP-link policy with effective database grants.OpenAPI / SwaggerREST API discovery and callsConnect an OpenAPI 3.x spec or supported docs page, inject upstream credentials, and restrict HTTP methods.

Choose a source and create an MCP link

Choose PostgreSQL, MySQL, or OpenAPI

Go to Connections → Add Connection. Add PostgreSQL or MySQL credentials, or provide an OpenAPI 3.x JSON/YAML URL, Swagger UI page, or Redoc page.

Create a source-specific MCP link

For a database, choose read-only, read-write, full, or table-specific operations. For OpenAPI, choose Read Only for GET/HEAD or Full Access for visible methods.

Connect your AI client

Copy the hosted MCP configuration into Cursor, Claude, VS Code, Windsurf, or Claude Code. The client receives database tools or OpenAPI discovery and call tools for the selected source.

MySQL connections

Connect MySQL with a dedicated database account and a standard mysql:// connection string, or enter the host, port, database, username, password, and TLS settings separately.

Create a least-privilege MySQL account for the intended schema and operations. Do not use root.
Go to Connections → New Connection → MySQL.
Add the connection details, choose the provider-appropriate TLS mode, then test and save.
Review the discovered tables, views, columns, keys, and indexes.
Create an MCP link and start with read-only access before granting writes.

Follow the MySQL and Cursor tutorial for user grants, mcp.json, and denial testing, or review the hosted MySQL MCP server overview.

Where to find your MCP URL and API key

Go to Dashboard → select your connection → MCP tab → click Setup Guide on your MCP link. The config snippet with your connection URL and API key will be ready to copy.

PostgreSQL connections

Connect PostgreSQL 12 or newer with a standard connection string. This includes hosted PostgreSQL from Supabase, Neon, AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL, Heroku, DigitalOcean, and self-hosted instances reachable by DataMCP.

Go to Connections → New Connection → PostgreSQL.
Paste the connection string or enter the host, port, database, username, password, and SSL mode.
Test and save the connection so DataMCP can extract the database schema.
Create an MCP link with the SQL operations and table scope required by the client.

For provider-specific details, see the Supabase MCP server guide or the PostgreSQL MCP server overview.

OpenAPI and Swagger connections

Connect a REST API from an OpenAPI 3.x JSON or YAML specification, or from a supported Swagger UI or Redoc documentation page. DataMCP extracts the API contract and exposes four MCP tools for endpoint discovery, schema inspection, and approved calls.

Go to Connections → New Connection → OpenAPI.
Paste the raw specification URL or the public Swagger UI or Redoc page URL.
Configure an API key, Bearer token, HTTP Basic credential, optional custom headers, or no upstream authentication.
Create a Read Only or Full Access MCP link and connect it to the AI client.

Start with the Swagger to MCP tutorial, follow the FastAPI MCP server guide, or review the complete OpenAPI to MCP product flow.

Cursor Setup

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

.cursor/mcp.json

{ "mcpServers": { "my-source": { "url": "https://api.datamcp.app/api/mcp/conn_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.

For source-specific walkthroughs, see Cursor with PostgreSQL , Cursor with MySQL, or Swagger to MCP.

Claude Desktop Setup

Claude and Claude Desktop add supported remote MCP servers through Customize → Connectors:

Choose Add custom connector and enter a recognizable name.
Paste the remote MCP URL shown in the DataMCP link setup guide.
Complete OAuth authentication, then enable the connector from Claude's Search and tools menu.

Anthropic currently lists remote custom connectors as a beta feature on Free, Pro, Max, Team, and Enterprise plans; Free accounts are limited to one custom connector. Team and Enterprise owners add organization connectors before members connect them. A new remote setup does not need mcp-remote.

For a full walkthrough, see Claude with PostgreSQL.

VS Code / Windsurf Setup

VS Code and Windsurf both support remote MCP, but their configuration files use different top-level keys.

VS Code

Create .vscode/mcp.json in the workspace, or run MCP: Open User Configuration for a profile-wide setup:

.vscode/mcp.json

{ "servers": { "my-source": { "type": "http", "url": "https://api.datamcp.app/api/mcp/conn_xxx", "headers": { "Authorization": "Bearer sk_live_..." } } } }

Run MCP: List Servers to inspect status and logs. Do not commit the API key placeholder replacement; use a secure input variable for a shared workspace file. See the complete VS Code MCP setup guide for the gallery, Command Palette, secure inputs, OAuth, local server sandboxing, and troubleshooting.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json and use mcpServers with a remote serverUrl:

mcp_config.json

{ "mcpServers": { "my-source": { "serverUrl": "https://api.datamcp.app/api/mcp/conn_xxx", "headers": { "Authorization": "Bearer sk_live_..." } } } }

Claude Code Setup

Claude Code supports remote HTTP MCP servers natively. Add the generated endpoint with the server name after the transport option:

Terminal

$ claude mcp add --transport http my-source
"https://api.datamcp.app/api/mcp/conn_xxx"
--header "Authorization: Bearer sk_live_..."

Run claude mcp list and then /mcp inside Claude Code to verify the connection. See the complete Claude Code MCP setup guide for project scope, .mcp.json, OAuth, and troubleshooting.

Permissions

Each MCP link has its own source-specific permission scope. PostgreSQL and MySQL links restrict SQL operations and tables; OpenAPI links restrict HTTP methods and endpoint visibility.

Database permission presets

Preset	Can do
Read-only	SELECT queries, view schema, view table details
Read, Write & Delete	Everything above + INSERT, UPDATE, DELETE
Full access	Operations permitted by the effective database account, including DDL when its grants allow it
Custom	Per-table access control. Choose which tables and operations to allow.

Database queries are validated against the MCP link and the effective PostgreSQL role or MySQL account before execution. Denied operations are logged in the activity trail. Use the Postgres AI access security kit for a non-owner PostgreSQL role, or the MySQL AI access security kit for a host-scoped account and explicit table grants. Both include allowed and denied validation paths.

OpenAPI access modes

Mode	Can do
Read Only	Discover visible operations and call GET or HEAD endpoints
Full Access	Call visible operations across configured HTTP methods, subject to upstream API authorization

Endpoint visibility can hide individual operations from discovery and execution. Read Only is a method gate, not proof that an allowed GET is side-effect-free or non-sensitive.

MCP Tools Reference

The tools exposed to an AI client depend on whether the MCP link belongs to a PostgreSQL, MySQL, or OpenAPI connection.

Database tools

`query`

Execute a SQL query against the database. Supports SELECT, INSERT, UPDATE, DELETE depending on permissions. Results limited to 100 rows, 30-second timeout.

`get_schema`

Get the cached database schema - tables, columns, types, foreign keys, indexes.

`get_table_details`

Get detailed information about a specific table including columns, constraints, and relationships.

`get_permissions`

Show the current permission scope for this MCP link - which tables and operations are allowed.

`get_schema_changes`

View schema change history - what changed between versions, with diffs.

`resync_schema`

Re-extract the schema from the live database. Use when the schema has changed (new tables, columns) and the cached version is outdated.

OpenAPI tools

`list_api_endpoints`

List the operations currently visible to this MCP link.

`get_endpoint_details`

Get the parameters, request body, and responses for one operation.

`get_api_schema`

Get the OpenAPI component schemas and their definitions.

`call_endpoint`

Call an approved operation. DataMCP injects the configured upstream credential; Read Only links permit GET and HEAD only.

OpenAPI authentication and access

Connect a REST API to your AI tools by pointing DataMCP at its OpenAPI 3.x specification. DataMCP exposes MCP tools for listing endpoints, inspecting operation details and schemas, and calling approved endpoints, with supported authentication handled server-side and access scoped by HTTP method.

Connection validation

Go to Connections → New Connection → OpenAPI.
Paste the URL of your OpenAPI 3.x spec. This can be a raw JSON/YAML spec or a documentation page (Redoc / Swagger UI): we extract the embedded spec automatically.
DataMCP validates the spec and shows how many endpoints it found. If the API declares authentication, we tell you which kind and pre-fill the header name.
Choose an auth method (or None for public APIs), add your credential, and create the connection.

Authentication

DataMCP stores the upstream credential encrypted and injects it into approved API calls, so it is not copied into the AI client configuration. Supported:

API key: sent in a header, query parameter, or cookie, using the location and name configured for the connection.
Bearer token: sent as Authorization: Bearer <token>.
HTTP Basic: username and password sent with HTTP Basic authentication.
Custom headers: optional fixed headers added to upstream requests.

Auth is used only for calling endpoints, not for fetching the spec. A public doc page validates fine with None, but if the API itself requires auth, calls will return 401 until you add a credential. The wizard flags this for you.

Access presets

When you create an MCP link for an OpenAPI connection, pick how much it can do:

Full Access: the AI can call visible operations across supported HTTP methods, subject to the upstream API's own authorization.
Read Only: only GET/HEAD; POST, PUT, PATCH, and DELETE are blocked.

Read Only is an HTTP method gate, not a guarantee that every allowed GET is side-effect-free or non-sensitive. The API owner remains responsible for endpoint semantics and upstream authorization.

PostgreSQL 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. Manual edits are preserved during ordinary schema resyncs; a full description regeneration replaces them.

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 & Edit_on 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.

Why this matters: AI clients perform dramatically better on ambiguous schemas when they can read “Stores Stripe subscription state per customer” instead of just subscriptions: id, customer_id, status, meta. Descriptions are the cheapest, highest-leverage thing you can do to improve query quality.

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 PostgreSQL, MySQL, or OpenAPI source 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

Role	Can do
Owner	Assigned to the organization creator. Full organization control, including members, billing, connections, MCP links, and organization deletion.
Admin	Manage members and organization resources. Organization deletion and ownership remain owner-only operations.
Member	Use organization resources allowed by the member's application and connection-level permissions. Cannot manage other members by default.

The current invitation flow offers Admin and Member. Owners and admins can further narrow member actions and connection access.

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.

Resource	Free	Pro $19/mo	Enterprise $49/mo
Source connections	1	10	Unlimited
MCP links	1	Unlimited	Unlimited
Organizations	1	3	Unlimited
Team members per org	2	10	Unlimited
Database activity retention	7 days	30 days	365 days

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 are not deleted solely because a resource limit is reached.

Upgrading

Go to Billing in the dashboard, choose a plan, and complete checkout via Stripe. The dashboard shows the active subscription and current resource usage.

See the full pricing page for a side-by-side comparison of all plans.

Database activity logs

PostgreSQL and MySQL queries plus denied database operations executed through MCP are logged automatically. OpenAPI endpoint calls are not currently included, so do not use this activity log as the audit source for upstream API execution.

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 date range, activity type, and status, search the available log data, and download the visible page as CSV or JSON.

PostgreSQL connection health

DataMCP checks active PostgreSQL connections and records their latest health state in the dashboard.

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

State	Meaning
Healthy	Database is reachable and accepting queries. MCP links serve traffic normally.
Paused	You manually paused the connection. All MCP links are disabled until you hit Resume.
Error	Five consecutive failed checks move the connection to Error and trigger an alert email to organization owners and admins. Requests can still reach the MCP endpoint, but database operations will fail until connectivity is restored.

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 database operations can succeed again.
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 becomes reachable again, the next successful hourly health check moves it back to Healthy. A successful PostgreSQL query also resets the accumulated health-check error count.

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

Diagnose source-specific failures before changing an MCP client configuration or expanding permissions.

OpenAPI and Swagger

The specification cannot be loaded

Confirm the URL is publicly reachable and serves an OpenAPI 3.x JSON/YAML document or a supported Swagger UI or Redoc page. DataMCP does not currently authenticate to a private specification URL.

API calls return 401 or 403

Check the upstream API key, Bearer token, Basic credential, and custom headers stored on the connection. A pre-issued Bearer token can be stored, but DataMCP does not obtain or refresh upstream OAuth tokens.

An operation is hidden or denied

A Read Only link permits GET and HEAD while blocking POST, PUT, PATCH, and DELETE. Also check whether endpoint visibility hides the operation from discovery and execution.

PostgreSQL

`no pg_hba.conf entry for host`

PostgreSQL is rejecting the hosted connection because its network or host-based access rules do not allow the request.

How to fix:

Add DataMCP's outbound IPs to your database's allowlist, security group, or firewall.
Confirm that the database role is allowed to connect to the selected database from the permitted network range.

`password authentication failed`

The username or password in your connection string is no longer valid.

How to fix:

Verify the credentials by connecting with psql or your favorite client.
Check whether the password or database role changed since the connection was created.
Open the connection in the dashboard, click Edit credentials, and paste a fresh connection string.

`timeout expired`

DataMCP could not establish or complete the database connection before the configured timeout.

Common causes:

The database server is down, paused, or still starting.
The hostname is no longer valid (e.g., instance was deleted and recreated).
The database sits behind a VPN, private network, or NAT gateway not accessible from the public internet.
The database is severely overloaded and can't accept new connections.

`self-signed certificate`

SSL/TLS negotiation failed because your database uses a self-signed or untrusted certificate and the SSL mode is set to strict verification.

How to fix:

Open the connection in the dashboard and click Edit credentials.
Prefer verify-full with a certificate chain trusted by the service.
If you choose require, understand that it encrypts transport without full server identity verification.

`no encryption`

Your database requires SSL but the connection was attempted without encryption.

How to fix:

Add ?sslmode=require to the end of your connection string.
Open the connection, click Edit credentials, and update the connection string or switch SSL mode to Require.

`database "xxx" does not exist`

The database name in your connection string doesn't match any database on the server.

How to fix:

Verify the database name is correct. Run \l in psql to list databases.
If the database was renamed or recreated, update the connection string.

MySQL

Access denied for user

Confirm the username, password, and MySQL user host rule. Inspect SHOW GRANTS for the dedicated account instead of testing with root.

Unknown database or incomplete schema

Include the database name in the connection, confirm the account can access that schema, and verify the provider network and TLS settings before widening database grants.

Still stuck?

Email hello@datamcp.appwith your connection name and the error message you're seeing. Do not include a password, connection string, API key, or MCP link secret.

Security

•Backend credential isolation: PostgreSQL and MySQL connection strings are encrypted at rest with AES-256-GCM. Supported upstream API credentials are stored on the OpenAPI connection and injected server-side rather than copied into the MCP client.
•API key storage: API keys use a SHA-256 hash for verification, an identifying prefix, and encrypted storage for the dashboard reveal flow.
•OAuth 2.0 with PKCE: MCP client authorization uses the OAuth 2.0 specification with PKCE for secure token exchange.
•Source-specific policy: Database queries are checked against SQL and table permissions. OpenAPI calls are checked against the link's method policy and endpoint visibility.
•SSL/TLS modes: Database TLS behavior is configurable. Use a verified mode whenever the PostgreSQL or MySQL provider supports it.
•Database activity: PostgreSQL and MySQL queries plus denied operations are logged with execution metadata. OpenAPI endpoint calls are not currently included in this activity log.

What's coming next?

See the roadmap for the current status of planned capabilities.

Recent updates

Check the changelog for a full history of shipped features and fixes.