MCP server and Claude Code

The open-source database-agent-mcp server lets MCP clients such as Claude Code ask your agents questions. It is a thin adapter over this API: every tool call is an ordinary request made with your API key, so the agent's table visibility, answer settings and limits all still apply. The server holds no database credentials and never writes SQL itself.

#Requirements

• Python 3.10 or later.
• A Database Agent agent and an API key for it (see the Quickstart).
• An MCP client. The steps below use Claude Code; any client that launches stdio servers works the same way.

#Install

pip install "git+https://github.com/FutureSmart-AI/database-agent.git#subdirectory=mcp-server"

This installs the database-agent-mcp command. With uv you can skip the install and run it on demand: uvx --from "git+https://github.com/FutureSmart-AI/database-agent.git#subdirectory=mcp-server" database-agent-mcp.

#Configure

The server reads its settings from environment variables and never prints them.

The server exits at start-up if no credential is set.

#Claude Code

#Per project, with .mcp.json

Add a .mcp.json to your project. Claude Code expands ${…} from your shell when it starts the server, so the file contains no secret and can be committed:

{
  "mcpServers": {
    "database-agent": {
      "command": "database-agent-mcp",
      "env": {
        "DATABASE_AGENT_URL": "https://futuresmart.ai/database-agent/api",
        "DATABASE_AGENT_AGENT_KEYS": "${DATABASE_AGENT_AGENT_KEYS}"
      }
    }
  }
}

Then set the key in the shell you start Claude Code from:

export DATABASE_AGENT_AGENT_KEYS="$DATABASE_AGENT_ID=$DATABASE_AGENT_API_KEY"
claude

#For every project, with claude mcp add

claude mcp add database-agent --scope user \
  -e DATABASE_AGENT_URL=https://futuresmart.ai/database-agent/api \
  -e "DATABASE_AGENT_AGENT_KEYS=$DATABASE_AGENT_ID=$DATABASE_AGENT_API_KEY" \
  -- database-agent-mcp

claude mcp add stores the values you pass in your Claude Code configuration file, key included.

#Check the connection

claude mcp list

The list should show database-agent: database-agent-mcp - ✔ Connected. A server defined in a project's .mcp.json shows Pending approval until you start claude in that folder and approve it once. Then ask, in Claude Code:

Using the database-agent tools, how many orders were placed in each month of 2025? Show the SQL. Then ask which month had the most, in the same conversation.

Claude Code calls list_agents, then ask_database, then ask_database again with the returned session_id. It asks your permission before each tool call unless you allow the tools.

#Tools

Every tool returns structured content with a published output schema. max_rows limits only the rows copied into the tool result; row_count and truncated describe the full result. SQL and rows appear only if the agent's Settings → Answers allows them — otherwise notes says so.

Errors come back as tool errors with the API's reason, for example Not permitted for agent NL2SQL_… (HTTP 403): This API key is not valid for this agent.

#Other MCP clients

Any client that starts stdio servers can use the same command and environment. In a client configured with an mcpServers JSON file:

{
  "mcpServers": {
    "database-agent": {
      "command": "database-agent-mcp",
      "env": {
        "DATABASE_AGENT_URL": "https://futuresmart.ai/database-agent/api",
        "DATABASE_AGENT_AGENT_KEYS": "NL2SQL_1A2B3C4D=your-key"
      }
    }
  }
}

If the client cannot find database-agent-mcp, give the full path that pip show -f database-agent-mcp or which database-agent-mcp reports.

#Limits and security

• The tools add no capability the API lacks: an MCP session can only do what your key can, and asks count toward the same daily question limit.
• A key can read every saved conversation on its agent, and so can the list_conversations and get_conversation tools.
• Give the agent a read-only database account. The adapter forwards questions; it cannot widen what that account or the agent's table visibility allows.
• Source: mcp-server/ and docs/mcp.md in the open-source repository.