Skip to main content

Overview

The Database MCP Agent is a conversational AI assistant that manages GibsonAI database projects using natural language. Built with Agno framework and the GibsonAI MCP server, it allows you to create projects, manage schemas, deploy changes, and query databases without writing SQL or complex commands.

Features

  • Create Projects - Start new database projects from scratch
  • Schema Management - Define tables, columns, and relationships
  • Deploy Changes - Apply schema changes to hosted databases
  • Natural Language - Interact using conversational commands
  • Best Practices - Get recommendations on database structure
  • Query Support - Interact with schema and data

Architecture

Prerequisites

  • Python 3.8+
  • GibsonAI account (gibson.ai)
  • Nebius API key
  • gibson-cli installed (via uvx or pipx)

Installation

1

Clone Repository

git clone https://github.com/your-username/awesome-llm-apps.git
cd awesome-llm-apps/mcp_ai_agents/database_mcp_agent
2

Create Virtual Environment

uv venv
source .venv/bin/activate
3

Install Dependencies

uv pip install -r requirements.txt
4

Configure Environment

Create a .env file:
NEBIUS_API_KEY=your_nebius_api_key
5

Install Gibson CLI

uvx --from gibson-cli@latest gibson --version

Usage

Basic Execution

python main.py

Custom Queries

Modify the message in main.py:
if __name__ == "__main__":
    asyncio.run(
        run_gibsonai_agent(
            '''
            Create a new GibsonAI project for my e-commerce store.
            It should have tables for products, customers, and orders.
            '''
        )
    )

MCP Integration

MCPTools Setup

The agent uses Agno’s MCPTools to connect to the GibsonAI MCP server:
from agno.tools.mcp import MCPTools

mcp_tools = MCPTools(
    "uvx --from gibson-cli@latest gibson mcp run",
    timeout_seconds=300,  # Extended timeout for database operations
)

# Connect to the MCP server
await mcp_tools.connect()

Agent Configuration

from agno.agent import Agent
from agno.models.nebius import Nebius
from textwrap import dedent
import os

agent = Agent(
    name="GibsonAIAgent",
    model=Nebius(
        id="meta-llama/Meta-Llama-3.1-70B-Instruct",
        api_key=os.getenv("NEBIUS_API_KEY")
    ),
    tools=[mcp_tools],
    description="Agent for managing database projects and schemas",
    instructions=dedent("""\
        You are a GibsonAI database assistant. Help users manage their 
        database projects and schemas.

        Your capabilities include:
        - Creating new GibsonAI projects
        - Managing database schemas (tables, columns, relationships)
        - Deploying schema changes to hosted databases
        - Querying database schemas and data
        - Providing insights about database structure and best practices
    """),
    markdown=True,
    show_tool_calls=True,
)

Complete Implementation

import asyncio
from textwrap import dedent
import os
from dotenv import load_dotenv
from agno.agent import Agent
from agno.models.nebius import Nebius
from agno.tools.mcp import MCPTools

load_dotenv()

async def run_gibsonai_agent(message: str):
    """Run the GibsonAI agent with the given message."""
    # Initialize MCP tools
    mcp_tools = MCPTools(
        "uvx --from gibson-cli@latest gibson mcp run",
        timeout_seconds=300,
    )

    # Connect to the MCP server
    await mcp_tools.connect()

    # Create agent
    agent = Agent(
        name="GibsonAIAgent",
        model=Nebius(
            id="meta-llama/Meta-Llama-3.1-70B-Instruct",
            api_key=os.getenv("NEBIUS_API_KEY")
        ),
        tools=[mcp_tools],
        description="Agent for managing database projects and schemas",
        instructions=dedent("""\
            You are a GibsonAI database assistant. Help users manage their
            database projects and schemas.

            Your capabilities include:
            - Creating new GibsonAI projects
            - Managing database schemas (tables, columns, relationships)
            - Deploying schema changes to hosted databases
            - Querying database schemas and data
            - Providing insights about database structure and best practices
        """),
        markdown=True,
        show_tool_calls=True,
    )

    # Run the agent
    await agent.aprint_response(message, stream=True)

    # Close the MCP connection
    await mcp_tools.close()

Usage Examples

await run_gibsonai_agent(
    """
    Create a new GibsonAI project for my Blog Application.
    You can decide the schema of the tables without double checking with me.
    """
)

MCP Tools Available

The GibsonAI MCP server provides the following tools through gibson-cli:
  • Create Project: Initialize new database project
  • List Projects: View all existing projects
  • Delete Project: Remove project and data
  • Get Project Details: View project configuration
  • Define Table: Create new table with columns
  • Modify Table: Update existing table structure
  • Delete Table: Remove table from schema
  • Add Column: Add new column to table
  • Modify Column: Update column properties
  • Drop Column: Remove column from table
  • Add Foreign Key: Define table relationships
  • Add Index: Create database indexes
  • Add Constraint: Define data constraints
  • Deploy Schema: Apply changes to database
  • Rollback: Revert to previous schema version
  • Generate Migration: Create migration scripts
  • Query Schema: Get schema information
  • Query Data: Execute database queries
  • Get Statistics: View database metrics

Advanced Features

Streaming Responses

The agent uses streaming for real-time feedback:
await agent.aprint_response(message, stream=True)

Tool Call Visibility

View MCP tool calls in real-time:
agent = Agent(
    ...,
    show_tool_calls=True,  # Display tool invocations
    markdown=True,          # Format output as markdown
)

Extended Timeouts

Database operations may take longer:
mcp_tools = MCPTools(
    "uvx --from gibson-cli@latest gibson mcp run",
    timeout_seconds=300,  # 5 minutes for complex operations
)

Connection Management

Always close MCP connections properly:
try:
    await mcp_tools.connect()
    # ... use agent ...
finally:
    await mcp_tools.close()

Best Practices

Schema Design

  • Use clear, descriptive table names
  • Define primary keys for all tables
  • Set up foreign key relationships
  • Add appropriate indexes

Agent Instructions

  • Provide clear, specific instructions
  • Let agent decide details when appropriate
  • Review schema before deploying
  • Use streaming for long operations

Error Handling

  • Always close MCP connections
  • Handle timeout exceptions
  • Validate user input
  • Log tool call errors

Security

  • Store API keys in environment variables
  • Use separate projects for development/production
  • Review schema changes before deployment
  • Implement backup strategies

Troubleshooting

Install or update gibson-cli:
uvx --from gibson-cli@latest gibson --version
# or
pipx install gibson-cli
Increase timeout for complex operations:
mcp_tools = MCPTools(
    "uvx --from gibson-cli@latest gibson mcp run",
    timeout_seconds=600,  # 10 minutes
)
Ensure environment variable is set:
echo $NEBIUS_API_KEY
# Should output your API key
Or check .env file exists and is loaded.
  • Verify project exists in GibsonAI
  • Check for schema validation errors
  • Review foreign key constraints
  • Ensure no circular dependencies

Source Code

View the complete implementation at: ~/workspace/source/mcp_ai_agents/database_mcp_agent/

GibsonAI

Database management platform

Agno Framework

Build AI agents with Agno

Couchbase MCP Server

Query Couchbase with MCP

Custom MCP Server

Build custom MCP servers

Build docs developers (and LLMs) love