MCP Integration Guide

This guide covers how to effectively integrate MCP (Model Context Protocol) servers with Girard to extend your AI's capabilities with external tools and services.

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI models to interact with external tools and services. It enables:

• Database Queries - Let AI query your databases
• File Access - Read and write files
• API Integration - Connect to external services
• Web Search - Access real-time information
• Automation - Control systems and services

How MCP Works

┌─────────────────────────────────────────────────────────┐
│                   User Request                          │
│     "Show me orders from last month"                    │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   AI Model                              │
│     Recognizes need for database query                  │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   MCP Server                            │
│     postgres.query_database()                           │
│     SELECT * FROM orders WHERE date > '2024-12-01'      │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│                   AI Response                           │
│     "Here are your 247 orders from last month..."       │
└─────────────────────────────────────────────────────────┘

Setting Up MCP Servers

Installing from Marketplace

1. Navigate to MCP in the sidebar
2. Go to the Marketplace tab
3. Find the server you want to install
4. Click Install
5. Configure connection settings
6. Click Connect

Server Configuration

Each server type requires specific configuration:

PostgreSQL

Name: Production Database
URL: postgresql://user:password@host:5432/database

Connection String Format:

postgresql://[user]:[password]@[host]:[port]/[database]

Tips:

• Use read-only credentials when possible
• Consider connection pooling for high volume
• Set appropriate timeouts

GitHub

Name: Company GitHub
URL: https://api.github.com
API Key: ghp_xxxxxxxxxxxxxxxxxxxx

Getting a Personal Access Token:

1. Go to GitHub Settings > Developer settings
2. Click Personal access tokens > Tokens (classic)
3. Generate new token with required scopes:
   • repo for repository access
   • read:org for organization data

Web Search

Name: Web Search
URL: (uses built-in service)

The web search MCP server is pre-configured and requires no additional setup.

Filesystem

Name: Local Files
Base Path: /path/to/allowed/directory

Security Note: Filesystem access is sandboxed to the specified path.

Using MCP Tools in Chat

Enabling Tools

1. Open the Chat interface
2. Expand the MCP Tools panel in the sidebar
3. Toggle the servers you want to enable
4. Start chatting

Effective Prompting with Tools

Help the AI know when to use tools:

Explicit Tool Request:

Search the web for the latest news about AI regulations.

Implicit Tool Usage:

What were our top-selling products last quarter?
(AI recognizes need for database query)

Multi-Tool Request:

Find our customer John Smith in the database and search
for any recent support tickets they've mentioned online.

Example Conversations

Database Query

User: Show me our revenue by month for 2024

AI: I'll query the database for that information.

[Executes: postgres.query_database]
SELECT
  DATE_TRUNC('month', created_at) as month,
  SUM(amount) as revenue
FROM orders
WHERE created_at >= '2024-01-01'
GROUP BY month
ORDER BY month;

Here's your 2024 revenue breakdown:

| Month | Revenue |
|-------|---------|
| Jan | $125,000 |
| Feb | $142,000 |
| Mar | $138,500 |
...

Web Research

User: What are the current best practices for React 19?

AI: Let me search for the latest information on React 19.

[Executes: web-search.search_web]

Based on recent articles and the official documentation,
here are the current best practices for React 19:

1. **Server Components** - Use server components by default...
2. **Actions** - New action-based form handling...
3. **use() Hook** - New hook for promises...

Sources:
- React Documentation (react.dev)
- "React 19 Best Practices" - Dev.to

File Operations

User: Read the config.json file and explain the settings

AI: I'll read that file for you.

[Executes: filesystem.read_file]

Here's your config.json file explained:

```json
{
  "apiEndpoint": "https://api.example.com",
  "timeout": 30000,
  "retries": 3
}

Settings breakdown:

• apiEndpoint: The base URL for API calls
• timeout: Request timeout in milliseconds (30 seconds)
• retries: Number of retry attempts for failed requests

---

## Using MCP Tools with Agents

### Configuring Agent Tools

When creating or editing an agent:

1. Scroll to the **MCP Servers** section
2. Toggle the servers relevant to the agent's purpose
3. Reference tools in the system prompt

### System Prompt Integration

Include tool guidance in your agent's system prompt:

```markdown
## Available Tools

You have access to the following MCP tools:

### Database (PostgreSQL)
- Query customer information
- Look up order history
- Search product catalog
- Access support tickets

When to use: Any question about specific customer data,
orders, or product information.

### Web Search
- Search for current information
- Find documentation
- Research competitors
- Get industry news

When to use: Questions about current events, external
information, or facts you're not certain about.

## Tool Usage Guidelines

1. **Database Queries**
   - Always use parameterized queries
   - Limit results when appropriate
   - Format data clearly in your response

2. **Web Search**
   - Search when you need current information
   - Cite sources in your response
   - Verify information from multiple sources if critical

Agent Tool Examples

Data Analyst Agent

You are a data analyst assistant with access to the company database.

## Available Data Sources
- orders: Customer orders and transactions
- products: Product catalog with pricing
- customers: Customer profiles and preferences
- support_tickets: Customer support history

## Analysis Capabilities
- Revenue analysis and trends
- Customer segmentation
- Product performance
- Support metrics

## When Querying Data
1. Understand the question fully
2. Write efficient SQL queries
3. Present data in clear tables/charts
4. Provide insights, not just numbers
5. Suggest follow-up analyses

Research Agent

You are a research assistant with web search capabilities.

## Research Process
1. Clarify the research question
2. Search for relevant sources
3. Evaluate source credibility
4. Synthesize information
5. Present findings with citations

## Source Evaluation
- Prefer official documentation
- Check publication dates
- Cross-reference claims
- Note limitations and biases

## Citation Format
Always include:
- Source title
- URL
- Publication date (if available)

Advanced Integration Patterns

Chained Tool Usage

AI can use multiple tools in sequence:

User: Find customers who haven't ordered in 6 months and
draft a re-engagement email.

AI: I'll query the database and then help draft an email.

[Step 1: Database Query]
SELECT email, name, last_order_date
FROM customers
WHERE last_order_date < NOW() - INTERVAL '6 months';

Found 234 inactive customers.

[Step 2: Draft Email]
Subject: We miss you, {name}!

Dear {name},

It's been a while since your last order...

Conditional Tool Usage

Use tools based on context:

## Tool Decision Framework

When asked about data:
1. If specific/internal data → Query Database
2. If general knowledge → Use your training
3. If current events/external → Web Search
4. If file content → Filesystem Read

Error Handling

Build in graceful error handling:

## When Tools Fail

If a tool call fails:
1. Acknowledge the issue to the user
2. Explain what you were trying to do
3. Offer an alternative approach
4. Ask if they want you to try again

Example:
"I tried to query the database but encountered a connection
error. Would you like me to try again, or can I help you
with something else while we investigate?"

Security Best Practices

Database Security

API Key Management

1. Use environment variables - Never hardcode keys
2. Rotate regularly - Change keys periodically
3. Least privilege - Grant minimum required permissions
4. Audit access - Monitor API key usage

Data Privacy

• Be aware of PII in database queries
• Don't expose sensitive data in responses
• Consider data residency requirements
• Log and audit tool usage

Troubleshooting

Server Won't Connect

Tools Not Being Used

1. Check tool is enabled - Toggle in Chat/Agent settings
2. Be explicit in prompts - "Search the web for..."
3. Verify server status - Check MCP page for connection status
4. Review system prompt - Include tool guidance

Slow Tool Responses

1. Optimize database queries
2. Reduce result set sizes
3. Check server performance
4. Consider caching frequently accessed data

Incorrect Tool Results

1. Verify data source is correct
2. Check query/search parameters
3. Review tool configuration
4. Test tool independently

Best Practices Summary

DO

• ✅ Use read-only credentials when possible
• ✅ Include tool guidance in system prompts
• ✅ Enable only necessary tools
• ✅ Monitor tool usage
• ✅ Handle errors gracefully
• ✅ Cite sources from web searches

DON'T

• ❌ Share sensitive credentials
• ❌ Enable all tools "just in case"
• ❌ Ignore security best practices
• ❌ Skip testing tool integrations
• ❌ Trust all tool results blindly

Girard AI MCP Server (stdio)

In addition to connecting external MCP servers, Girard AI provides its own MCP server that can be used with local AI tools like Claude Code.

Quick Start

Add the server to your Claude Code configuration:

{
  "mcpServers": {
    "girard-ai": {
      "command": "npx",
      "args": ["tsx", "/path/to/girardai-com/bin/mcp-server.ts"],
      "env": {
        "MCP_ORGANIZATION_ID": "your-org-id",
        "MCP_USER_ID": "your-user-id"
      }
    }
  }
}

Running Standalone

# Run with tsx directly
npx tsx bin/mcp-server.ts --debug

# Or use the npm script
npm run mcp:debug

# Or use the launcher script
node scripts/mcp-server.js --debug

Environment Variables

Available Tools (31+)

Available Resources (11+)

Testing the Server

# Test initialize
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0"}}}' | npm run mcp

# Test tool list
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | npm run mcp

# Test ping
echo '{"jsonrpc":"2.0","id":3,"method":"ping"}' | npm run mcp

Previous: Creating Agents | Next: Building Workflows