lovelace mcp

Integrate Model Context Protocol (MCP) servers for extended AI capabilities

The MCP command provides integration with Model Context Protocol servers, allowing AI assistants to access external tools, databases, APIs, and services through a standardized protocol. MCP servers extend your CLI's capabilities beyond built-in features.

Overview

Model Context Protocol (MCP) is an open protocol that enables AI systems to securely connect with external data sources and tools. With Lovelace MCP integration, you can:

Access filesystems - Read, write, and navigate files through MCP
Query databases - Execute SQL queries and manage database connections
Call APIs - Integrate with Linear, GitHub, Jira, and custom APIs
Execute tools - Run custom tools and scripts through MCP servers
Interactive REPL - Explore MCP capabilities interactively

MCP servers run separately and communicate with Lovelace through a standardized protocol, providing secure, controlled access to resources.

Usage

bash

lovelace mcp <subcommand> [options]

Subcommands

`lovelace mcp servers`

Manage MCP server configurations.

Usage:

bash

lovelace mcp servers <action> [options]

Actions:

list - List all configured servers
add - Add a new MCP server
remove - Remove an MCP server
status - Check server connection status

Interactive Example:

$ lovelace mcp servers list

Configured MCP Servers
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Name         │ Type    │ Status      │ Tools Available
─────────────┼─────────┼─────────────┼────────────────
filesystem   │ stdio   │ Connected   │ 8 tools
database     │ stdio   │ Connected   │ 12 tools
linear       │ stdio   │ Connected   │ 15 tools
github       │ http    │ Disconnected│ -

4 servers configured, 3 connected

Adding a server:

$ lovelace mcp servers add myserver stdio --command "node /path/to/server.js"

✓ Server added: myserver

Configuration:
  Name: myserver
  Type: stdio
  Command: node /path/to/server.js

Test connection:
  lovelace mcp servers status myserver

`lovelace mcp repl`

Launch interactive MCP REPL session.

Usage:

bash

lovelace mcp repl [server-name] [options]

Interactive Example:

$ lovelace mcp repl filesystem

🔌 MCP REPL - filesystem server
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Connected to: filesystem
Available tools: 8
Type 'help' for commands, 'exit' to quit

mcp> help

Available Commands:
  tools              List available tools
  call <tool> [args] Execute a tool
  resources          List available resources
  help              Show this help message
  exit              Exit REPL

mcp> tools

Available Tools from filesystem:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
read_file          Read file contents
write_file         Write content to file
list_directory     List directory contents
create_directory   Create new directory
delete_file        Delete a file
move_file          Move or rename file
search_files       Search for files
file_info          Get file metadata

mcp> call read_file path="/Users/dev/config.json"

Executing: read_file
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{
  "api_key": "***",
  "endpoint": "https://api.example.com",
  "timeout": 5000
}

✓ Command executed successfully

mcp> call list_directory path="/Users/dev/project"

Executing: list_directory
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Directory: /Users/dev/project

Files (12):
  README.md
  package.json
  tsconfig.json
  ...

Directories (4):
  src/
  tests/
  docs/
  node_modules/

✓ Command executed successfully

mcp> exit

Goodbye!

`lovelace mcp exec`

Execute a single MCP tool command.

Usage:

bash

lovelace mcp exec <command> [options]

Arguments:

Argument	Description	Required
`command`	Tool call expression	Yes

Interactive Example:

$ lovelace mcp exec "list_files(path='/tmp')"

Executing MCP Command
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Server: filesystem
Tool: list_files
Arguments: {path: '/tmp'}

Result:
Files found: 47

[List of files...]

✓ Execution completed in 0.234s

With multiple arguments:

$ lovelace mcp exec "create_issue(title='Bug fix', labels=['bug', 'urgent'])"

Executing MCP Command
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Server: linear
Tool: create_issue
Arguments: {
  title: 'Bug fix',
  labels: ['bug', 'urgent']
}

Result:
✓ Issue created: ENG-1234
  URL: https://linear.app/team/issue/ENG-1234
  Status: Todo
  Labels: bug, urgent

✓ Execution completed in 1.523s

`lovelace mcp sessions`

Manage MCP session history.

Usage:

bash

lovelace mcp sessions <action> [options]

Actions:

list - List recent MCP sessions
search - Search session history

Interactive Example:

$ lovelace mcp sessions list

Recent MCP Sessions
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Session ID       │ Server     │ Commands │ Duration │ Date
─────────────────┼────────────┼──────────┼──────────┼────────────
sess_abc123      │ filesystem │ 8        │ 5m 23s   │ 2025-10-19
sess_xyz789      │ linear     │ 3        │ 1m 12s   │ 2025-10-19
sess_def456      │ database   │ 15       │ 12m 45s  │ 2025-10-18

$ lovelace mcp sessions search "create_issue"

Search Results: "create_issue"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Found in 3 sessions:

Session sess_xyz789 (2025-10-19):
  ├─ create_issue(title='Feature request')
  ├─ create_issue(title='Bug fix')
  └─ update_issue(id='ENG-1234', status='Done')

Session sess_pqr012 (2025-10-18):
  └─ create_issue(title='Documentation update')

[...]

Common Use Cases

File Operations

Access files through MCP filesystem server:

$ lovelace mcp repl filesystem

mcp> call read_file path="/Users/dev/src/config.ts"

[File contents displayed]

mcp> call write_file path="/Users/dev/notes.md" content="# Meeting Notes..."

✓ File written successfully

mcp> call search_files pattern="*.test.ts" path="/Users/dev/src"

Found 47 test files:
  src/auth/login.test.ts
  src/api/users.test.ts
  [...]

Database Queries

Query databases through MCP:

$ lovelace mcp exec "query('SELECT * FROM users LIMIT 10')"

Query Results:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
10 rows returned

id │ email                │ created_at
───┼──────────────────────┼────────────
1  │ user@example.com     │ 2025-10-01
2  │ admin@example.com    │ 2025-10-02
[...]

✓ Query executed in 0.045s

Linear Integration

Manage Linear issues:

$ lovelace mcp repl linear

mcp> tools

Available Tools:
  list_issues        List issues
  create_issue       Create new issue
  update_issue       Update issue
  add_comment        Add comment
  list_projects      List projects
  [...]

mcp> call list_issues assignee="me" status="active"

Your Active Issues:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ENG-1234: Implement OAuth authentication
  Status: In Progress
  Priority: High

ENG-1235: Fix memory leak
  Status: Todo
  Priority: Urgent

[...]

mcp> call create_issue title="Add rate limiting" labels=["enhancement"]

✓ Issue created: ENG-1236

GitHub Operations

Interact with GitHub repositories:

$ lovelace mcp exec "list_pull_requests(repo='myorg/myrepo', state='open')"

Open Pull Requests
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#123: Add authentication
  Author: @user1
  Status: Ready for review
  +245 -67

#124: Fix bug in user service
  Author: @user2
  Status: Changes requested
  +12 -8

[...]

MCP Server Configuration

MCP servers are configured in ~/.lovelace/mcp/config.json:

json

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/dev"]
    },
    "linear": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": {
        "LINEAR_API_KEY": "lin_api_..."
      }
    },
    "database": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/db-server.js"],
      "env": {
        "DATABASE_URL": "postgresql://..."
      }
    }
  }
}

Available MCP Servers

Popular MCP servers you can integrate:

Server	Purpose	Install
filesystem	File operations	`npx @modelcontextprotocol/server-filesystem`
linear	Linear issue management	`npx @modelcontextprotocol/server-linear`
github	GitHub operations	`npx @modelcontextprotocol/server-github`
database	SQL database queries	Custom server
slack	Slack messaging	Custom server

See MCP Server Directory for more servers.

Security Considerations

MCP servers have access to resources you configure. Follow these security practices:

Principle of Least Privilege

json

// ✅ Good: Limit filesystem access to specific directories
{
  "filesystem": {
    "command": "npx @modelcontextprotocol/server-filesystem",
    "args": ["/Users/dev/safe-directory"]
  }
}

// ❌ Bad: Unrestricted filesystem access
{
  "filesystem": {
    "args": ["/"]  // Entire filesystem accessible
  }
}

API Key Management

json

// ✅ Good: Use environment variables
{
  "linear": {
    "env": {
      "LINEAR_API_KEY": "${LINEAR_API_KEY}"  // From shell environment
    }
  }
}

// ❌ Bad: Hardcoded keys
{
  "linear": {
    "env": {
      "LINEAR_API_KEY": "lin_api_actual_key_here"
    }
  }
}

Connection Security

Only connect to trusted MCP servers
Verify server source code before use
Use HTTPS for HTTP-based MCP servers
Regularly update MCP server packages

Tips & Best Practices

Discovering Tools

bash

# List all available tools across servers
lovelace mcp servers status

# Explore specific server
lovelace mcp repl filesystem
mcp> tools
mcp> help read_file  # Get tool documentation

Combining with Chat

MCP tools are automatically available in chat sessions:

$ lovelace chat

You: List all issues assigned to me in Linear

🤖 I'll query Linear for your issues using the MCP integration.

[Executes: list_issues(assignee="me")]

You have 5 active issues:
1. ENG-1234: Implement OAuth
2. ENG-1235: Fix memory leak
[...]

Batch Operations

bash

# Execute multiple commands
lovelace mcp repl linear <<EOF
call list_issues status="todo"
call create_issue title="New feature"
call list_issues status="todo"
exit
EOF

Environment Variables

Variable	Description	Default
`LOVELACE_MCP_CONFIG`	Path to MCP config file	`~/.lovelace/mcp/config.json`
`MCP_SERVER_TIMEOUT`	Server connection timeout (ms)	`5000`

Exit Codes

Code	Meaning
`0`	Command succeeded
`1`	MCP server error or connection failure
`2`	Invalid arguments
`3`	Server not configured

Troubleshooting

Server Not Connecting

$ lovelace mcp servers status

filesystem: Disconnected

Solution:
# Check server configuration
cat ~/.lovelace/mcp/config.json

# Test server manually
npx @modelcontextprotocol/server-filesystem /Users/dev

# Check server logs
lovelace mcp servers logs filesystem

Tool Not Found

mcp> call nonexistent_tool

Error: Tool not found: nonexistent_tool

Solution:
mcp> tools  # List available tools

Permission Denied

mcp> call read_file path="/etc/passwd"

Error: Permission denied

Solution: MCP servers respect system permissions.
Ensure the server has access to the requested path.

Related Commands

lovelace chat - MCP tools available in chat
lovelace agents - Agents can use MCP tools
lovelace config - Configure MCP settings

Related Guides

MCP Integration Guide - Complete MCP features
Linear Integration - Linear MCP setup

See the Command Reference for all available commands.

Learn more about MCP: Model Context Protocol

Lovelace Developer Portal

lovelace mcp

Overview

Usage

Subcommands

`lovelace mcp servers`

`lovelace mcp repl`

`lovelace mcp exec`

`lovelace mcp sessions`

Common Use Cases

File Operations

Database Queries

Linear Integration

GitHub Operations

MCP Server Configuration

Available MCP Servers

Security Considerations

Principle of Least Privilege

API Key Management

Connection Security

Tips & Best Practices

Discovering Tools

Combining with Chat

Batch Operations

Environment Variables

Exit Codes

Troubleshooting

Server Not Connecting

Tool Not Found

Permission Denied

Related Commands

Related Guides

Lovelace Developer Portal