MCP Integration Guide

Complete guide to Model Context Protocol servers and capabilities

Overview

Model Context Protocol (MCP) extends the Lovelace CLI with additional capabilities through standardized server connections. MCP servers provide filesystem access, database connectivity, API integrations, and custom tool implementations.

Understanding MCP

What is MCP?

Model Context Protocol is:

Standardized interface for connecting AI systems to external resources
Server-based architecture where servers provide specific capabilities
Tool and resource provider that extends AI functionality
Secure connection method with proper authentication and authorization

MCP vs ACP

Protocol	Purpose	Use Case
MCP	AI ↔ Resources	File access, databases, APIs, tools
ACP	Editors ↔ Platform	Editor integration, agent orchestration

MCP Server Management

List Available Servers

bash

# List all MCP servers
lovelace mcp servers

# List servers by category
lovelace mcp servers --category filesystem
lovelace mcp servers --category database
lovelace mcp servers --category api

# List running servers
lovelace mcp servers --status running

# List server capabilities
lovelace mcp servers --capabilities

Common MCP Servers:

filesystem - File and directory operations
database - Database queries and operations
git - Git repository operations
web - Web scraping and HTTP requests
terminal - Shell command execution
cloud - Cloud service integrations

Server Information

bash

# Get detailed server information
lovelace mcp info filesystem

# Check server health
lovelace mcp ping filesystem

# View server configuration
lovelace mcp config filesystem

# List server tools
lovelace mcp tools filesystem

Server Connection

bash

# Connect to MCP server
lovelace mcp connect filesystem

# Connect with authentication
lovelace mcp connect database --auth credentials.json

# Connect with custom configuration
lovelace mcp connect api --config api-config.json

# Disconnect from server
lovelace mcp disconnect filesystem

Interactive MCP Usage

MCP REPL

bash

# Start interactive REPL
lovelace mcp repl

# Start REPL with specific server
lovelace mcp repl filesystem

# Start REPL with multiple servers
lovelace mcp repl filesystem,database,git

REPL Commands:

/servers - List connected servers
/tools - List available tools
/help <tool> - Get help for specific tool
/use <server> - Switch active server
/exit - Exit REPL

Example REPL Session

> lovelace mcp repl filesystem

MCP REPL - Connected to: filesystem
Available tools: read_file, write_file, list_directory, create_directory

mcp> read_file src/components/Button.tsx

[File contents displayed]

mcp> list_directory src/components/
- Button.tsx
- Input.tsx
- Modal.tsx
- index.ts

mcp> /use git
Switched to git server

mcp> git_log --max-count 5
[Recent git commits displayed]

mcp> /exit

Direct Command Execution

Execute MCP Commands

bash

# Execute tool directly
lovelace mcp exec filesystem read_file src/config.ts

# Execute with parameters
lovelace mcp exec database query "SELECT * FROM users LIMIT 10"

# Execute with JSON parameters
lovelace mcp exec api request --method POST --url /api/users --data '{"name":"John"}'

# Execute with file input
lovelace mcp exec filesystem write_file --path output.txt --content @input.txt

Batch Operations

bash

# Execute multiple commands
lovelace mcp batch commands.txt

# Execute commands from script
lovelace mcp script automation.mcp

# Pipeline operations
lovelace mcp exec filesystem list_directory src/ | \
lovelace mcp exec filesystem read_file

MCP in AI Chat

Chat with MCP Access

bash

# Start chat with MCP servers
lovelace chat --mcp filesystem,database

# Chat with specific MCP configuration
lovelace chat --mcp-config mcp-setup.json

# Chat with all available MCP servers
lovelace chat --mcp-all

MCP-Enhanced Conversations

You: Show me the contents of the authentication configuration file

AI: I'll read the authentication configuration file for you.

[Uses MCP filesystem server]
Reading: src/config/auth.config.ts

```typescript
export const authConfig = {
  providers: ['google', 'github'],
  session: {
    maxAge: 30 * 24 * 60 * 60, // 30 days
    strategy: 'jwt'
  },
  callbacks: {
    jwt: async ({ token, user }) => {
      if (user) token.id = user.id;
      return token;
    }
  }
};

The configuration shows a multi-provider setup with JWT sessions. Would you like me to analyze any specific aspect or suggest improvements?

You: Check if there are any recent changes to authentication in git

AI: I'll check the recent git history for authentication-related changes.

[Uses MCP git server] Git log for auth-related files:

commit abc123 (2 days ago): "Add OAuth error handling"
commit def456 (5 days ago): "Update session configuration"
commit ghi789 (1 week ago): "Implement refresh token rotation"

The most recent change added OAuth error handling. Would you like me to show the details of any of these commits?


## Server Configuration

### Filesystem Server

```json
// filesystem-config.json
{
  "server": "filesystem",
  "config": {
    "allowed_paths": [
      "./src",
      "./docs",
      "./config"
    ],
    "denied_patterns": [
      "**/.env*",
      "**/node_modules/**",
      "**/.git/**"
    ],
    "max_file_size": "10MB",
    "read_only": false
  }
}

Database Server

json

// database-config.json
{
  "server": "database",
  "config": {
    "connection": {
      "host": "localhost",
      "port": 5432,
      "database": "development",
      "ssl": false
    },
    "query_timeout": 30000,
    "max_rows": 1000,
    "allowed_schemas": ["public", "auth"],
    "read_only": true
  }
}

API Server

json

// api-config.json
{
  "server": "api",
  "config": {
    "base_url": "https://api.example.com",
    "authentication": {
      "type": "bearer",
      "token_env": "API_TOKEN"
    },
    "rate_limit": {
      "requests_per_minute": 100
    },
    "allowed_methods": ["GET", "POST"],
    "timeout": 10000
  }
}

Session Management

MCP Sessions

bash

# List MCP sessions
lovelace mcp sessions list

# Create named session
lovelace mcp sessions create development-session

# Join existing session
lovelace mcp sessions join development-session

# Save session state
lovelace mcp sessions save development-session

# Load session state
lovelace mcp sessions load development-session

Session Persistence

bash

# Enable session persistence
lovelace config set mcp.persist_sessions true

# Set session timeout
lovelace config set mcp.session_timeout 3600

# Clean up old sessions
lovelace mcp sessions cleanup

# Clear all sessions
lovelace mcp sessions clear

Advanced MCP Features

Custom MCP Servers

python

# custom-server.py - Example custom MCP server
from mcp import Server, Tool

server = Server("custom-tools")

@server.tool("analyze_code")
async def analyze_code(file_path: str) -> str:
    """Analyze code quality for a given file."""
    # Custom analysis implementation
    return analysis_result

@server.tool("generate_tests")
async def generate_tests(source_file: str) -> str:
    """Generate unit tests for source file."""
    # Test generation implementation
    return test_code

if __name__ == "__main__":
    server.run()

bash

# Connect to custom server
lovelace mcp connect custom-tools --url http://localhost:8000

Server Composition

yaml

# mcp-composition.yaml
name: "Development Environment"
servers:
  - name: filesystem
    config: filesystem-config.json
  - name: database
    config: database-config.json
  - name: git
    config: git-config.json
  - name: custom-tools
    url: http://localhost:8000

workflows:
  - name: "code-review"
    steps:
      - server: git
        tool: get_diff
      - server: filesystem
        tool: read_files
      - server: custom-tools
        tool: analyze_code

bash

# Load composition
lovelace mcp load-composition mcp-composition.yaml

Integration Patterns

MCP with Agent Workers

bash

# Run agent with MCP access
lovelace agents run analysis-worker --mcp filesystem,git

# Configure agent MCP permissions
lovelace agents config analysis-worker --mcp-permissions read-only

MCP in Editor Integration

bash

# Start ACP with MCP servers
lovelace acp start --mcp filesystem,database

# Configure editor MCP access
lovelace config set acp.mcp_servers "filesystem,git"

MCP Automation

bash

# Scheduled MCP operations
lovelace mcp schedule --daily "backup-database"

# MCP webhooks
lovelace mcp webhook --on-file-change "run-tests"

# MCP monitoring
lovelace mcp monitor --alert-on-error

Security and Permissions

Access Control

bash

# Set MCP permissions
lovelace mcp permissions filesystem --read-only
lovelace mcp permissions database --query-only

# Create permission profiles
lovelace mcp permissions create-profile developer
lovelace mcp permissions assign-profile developer filesystem,git

# Audit MCP access
lovelace mcp audit --server filesystem

Authentication

bash

# Configure server authentication
lovelace mcp auth filesystem --method token --token-file auth.token

# Use environment variables
export MCP_DATABASE_PASSWORD=secret
lovelace mcp connect database

# Secure credential storage
lovelace mcp credentials set database --user admin --password-prompt

Troubleshooting

Connection Issues

Server Not Responding

bash

# Check server status
lovelace mcp ping filesystem

# Test server connectivity
lovelace mcp test-connection filesystem

# Restart server connection
lovelace mcp reconnect filesystem

# Check server logs
lovelace mcp logs filesystem

Authentication Failures

bash

# Verify credentials
lovelace mcp auth test database

# Reset authentication
lovelace mcp auth reset database

# Use different auth method
lovelace mcp auth database --method oauth

Performance Issues

Slow Operations

bash

# Enable MCP operation caching
lovelace config set mcp.cache_operations true

# Increase timeout values
lovelace config set mcp.timeout 60000

# Optimize query patterns
lovelace mcp optimize --server database

Resource Usage

bash

# Monitor MCP resource usage
lovelace mcp resources

# Limit concurrent operations
lovelace config set mcp.max_concurrent 5

# Clean up MCP cache
lovelace mcp cache clear

Best Practices

Server Management

Use appropriate servers - Connect only needed servers for security
Configure permissions - Set minimal required permissions
Monitor usage - Track MCP server usage and performance
Regular updates - Keep MCP servers updated for security

Performance

Cache frequently used data - Enable caching for repeated operations
Limit query scope - Use specific queries rather than broad scans
Connection pooling - Reuse connections when possible
Async operations - Use async operations for better performance

Security

Principle of least privilege - Grant minimal required access
Secure credentials - Use secure credential storage methods
Audit access - Regularly audit MCP server access logs
Network security - Use encrypted connections for remote servers

Next Steps:

Editor Integration - Use MCP from your editor
Agent Execution - Combine MCP with agent workers
Advanced Configuration - Detailed MCP configuration