MCP Integration

MCP Integration

Use dbward from AI-powered IDEs (Cursor, GitHub Copilot, Kiro) via the Model Context Protocol. The AI can query databases, run migrations, and check request status — all through dbward’s approval workflow.

Why MCP?

• AI never gets DB credentials — all operations go through dbward’s approval engine
• Same workflow for humans and AI — production queries still require human approval
• Full audit trail — every AI-initiated operation is logged with the AI tool as actor

Setup

1. Configure dbward client

Ensure you have a working client configuration. For stdio mode, the CLI needs to know your server URL and credentials:

Global config (~/.config/dbward/config.toml):

[server]
url = "https://dbward.internal:3000"
token = "dbw_..."

Or use OIDC: dbward login

2. Add to your IDE

dbward supports two transports: stdio (local binary) and Remote HTTP (server-hosted, no local install needed).

Option A: stdio (local binary)

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "dbward": {
      "command": "dbward",
      "args": ["mcp"],
      "env": {}
    }
  }
}

GitHub Copilot (VS Code)

Add to .vscode/mcp.json:

{
  "servers": {
    "dbward": {
      "command": "dbward",
      "args": ["mcp"]
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "dbward": {
      "command": "dbward",
      "args": ["mcp"],
      "transportType": "stdio"
    }
  }
}

Option B: Remote HTTP (no local binary)

The dbward server exposes MCP at /mcp. Team members don’t need the CLI installed — just point their IDE at the server:

Cursor

{
  "mcpServers": {
    "dbward": {
      "type": "streamable-http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

GitHub Copilot (VS Code)

{
  "servers": {
    "dbward": {
      "type": "http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

Kiro

{
  "mcpServers": {
    "dbward": {
      "transportType": "streamable-http",
      "url": "https://your-server.example.com/mcp"
    }
  }
}

Authentication: Remote HTTP uses the same token or OIDC as the REST API. The IDE passes credentials via the Authorization header. Ensure your dbward.toml has a valid token or that you’ve run dbward login.

Transport comparison

	stdio	Remote HTTP
Requires local dbward binary	✅	❌
Works offline (local dev)	✅	❌
Centralized for teams	❌	✅
Tools available	12	9 (excludes local-only migration tools)
Prompts available	6	4 (excludes file-dependent prompts)
Elicitation support	IDE-dependent	IDE-dependent

3. Verify

Ask your AI assistant: “What tables are in the database?” — it should use dbward_inspect_schema to answer.

If the AI can’t connect, run dbward doctor to check that the server URL and token are correctly configured.

Available tools (12)

Full parameter reference: MCP Reference

Database operations

Tool	Description
dbward_execute_query	Execute SQL (goes through approval workflow)
dbward_inspect_schema	Inspect schema (list tables or describe columns)
dbward_preflight_sql	Analyze SQL before submitting (risk, policy, EXPLAIN)

Request management

Tool	Description
dbward_wait_request	Wait for request completion and return result
dbward_list_pending	List requests awaiting approval
dbward_who_can_approve	Show who can approve a request
dbward_find_similar_requests	Find similar past requests

Migrations

Tool	Description
dbward_migrate_status	Show migration status
dbward_migrate_up	Apply migrations
dbward_migrate_down	Rollback migrations
dbward_migrate_create	Create migration files (local)

Analysis

Tool	Description
dbward_explain_policy_failure	Explain why a request was blocked

How approval works with AI

When the AI executes a query that requires approval:

1. AI calls dbward_execute_query → request created (status: pending)
2. If the IDE supports elicitation, dbward asks the user for confirmation directly in the IDE
3. Otherwise, the AI reports the request ID and waits
4. A human approves via CLI, another IDE, or Slack
5. AI calls dbward_wait_request to wait for approval and result
6. Once complete, the result is returned directly

How AI agents use preflight

AI agents should call dbward_preflight_sql before submitting SQL to avoid polluting the approval queue with unsafe or blocked queries:

1. AI drafts SQL based on user request
2. AI calls dbward_preflight_sql to validate
3. If status is blocked — AI reads fix_hints and next_actions, rewrites the SQL, and retries preflight
4. If status is warning — AI informs the user of risks before proceeding
5. If status is requestable — AI calls dbward_execute_query to submit

This loop lets the AI converge on safe SQL without human intervention or creating unnecessary requests. The preflight call is lightweight and does not require approval.

Resources

The MCP server exposes read-only resources:

Resource	Description
dbward://migrations/status	Current migration state
dbward://requests/pending	Pending approval requests
dbward://audit/recent	Recent audit events
dbward://requests/{id}	Specific request details (template)
dbward://schema/{database}	Table list with row counts (from agent snapshot)
dbward://schema/{database}/{table}	Column, constraint, and index details for a table

Schema resources

Schema resources return data from agent-collected snapshots (no live DB query needed).

dbward://schema/app          → all tables (name, schema, rows, column count)
dbward://schema/app/users    → full details for 'users' table
dbward://schema/app/public.orders → schema-qualified lookup

The server automatically resolves the best environment (production > staging > development) based on snapshot availability and your permissions. The response includes environment and collected_at so you know which snapshot you’re seeing.

If no snapshot is available yet, start an agent for the database — it collects schema on startup.

Prompts

Pre-built prompts for common AI workflows:

Prompt	Description
review_migration	Review a migration for safety issues
explain_request	Explain what a request will do
draft_migration	Generate migration SQL from a description
draft_rollback	Generate rollback SQL for a migration
summarize_audit_trail	Summarize recent audit events
prepare_approval_comment	Draft an approval comment

Example conversation

You: “Add an index on users.email for faster lookups”

AI: I’ll create a migration for that. [calls dbward_migrate_create with name “add_users_email_index”]

Created db/migrations/20260508_add_users_email_index/up.sql. Here’s the SQL:

CREATE INDEX CONCURRENTLY idx_users_email ON users (email);

You: “Apply it to staging”

AI: [calls dbward_migrate_up with environment “staging”]

✓ Migration applied to staging (auto-approved).

You: “Now apply to production”

AI: [calls dbward_migrate_up with environment “production”]

⚠ Request req_m3x4 requires approval from dba-team. I’ll check back when it’s approved.

[waits with dbward_wait_request]

✓ Approved by bob@example.com. Migration applied successfully.

Security considerations

• The AI tool authenticates as the user’s identity (their token or OIDC session)
• The AI cannot bypass approval workflows — --emergency is blocked via MCP
• All AI-initiated operations appear in the audit log
• The AI never sees database credentials

Async approval (Elicitation)

When a query requires approval, dbward uses MCP’s Elicitation feature to pause and wait:

1. AI calls dbward_execute_query
2. Server responds: “approval required”
3. MCP tool uses elicitation to inform the user and wait (timeout: 300 seconds)
4. If a reason is required by the workflow, elicitation prompts the user for it
5. Once approved (via CLI, API, or Slack), the tool resumes and returns the result

If the IDE doesn’t support elicitation, the tool falls back to polling with dbward_wait_request.

See also

• Workflows — Configure what requires approval
• Authentication — Token setup for MCP
• MCP Reference — Complete tools/resources/prompts list