# MCP CLI Commands
Command reference for mcp. Use the installed command’s `--help` output for its complete arguments and defaults.
---
## Prerequisites
```bash
export SYSTEMPROMPT_PROFILE=~/.systemprompt/profiles/local/profile.yaml
cd /var/www/html/systemprompt-core
cargo build --package systemprompt-cli
alias sp="./target/debug/systemprompt --non-interactive"
```
---
## Command Reference
| `plugins mcp list` | List configured MCP servers | `Table` | No |
| `plugins mcp status` | Show MCP server runtime status | `Table` | Yes |
| `plugins mcp validate [name]` | Validate MCP server configurations | `Card` | Yes |
| `plugins mcp validate --all` | Validate all configured servers | `Card` | Yes |
| `plugins mcp logs [name]` | Tail logs for an MCP server | `Text` | No |
| `plugins mcp list-packages` | List discovered MCP packages from the registry | `List` | Yes |
| `plugins mcp tools` | List tools exposed by enabled MCP servers | `Table` | Yes |
| `plugins mcp call <server> <tool>` | Invoke a tool on an MCP server | `Card` | Yes |
---
## Core Commands
### mcp list
List configured MCP servers from the services configuration, filterable by enabled or disabled state.
```bash
sp plugins mcp list
sp --json plugins mcp list
sp plugins mcp list --enabled
sp plugins mcp list --disabled
```
**Flags:**
| `--enabled` | Show only enabled servers |
| `--disabled` | Show only disabled servers |
**Output Structure:**
```json
{
"servers": [
{
"name": "filesystem",
"display_name": "filesystem",
"server_type": "internal",
"port": 9001,
"enabled": true,
"status": "ready",
"binary_debug": "/path/to/target/debug/mcp-filesystem",
"binary_release": "/path/to/target/release/mcp-filesystem"
}
]
}
```
**Status Values:**
- `ready` - Both debug and release binaries exist
- `debug-only` - Only debug binary exists
- `release-only` - Only release binary exists
- `not-built` - No binaries exist
- `disabled` - Server is disabled in configuration
- `remote` - External server, enabled
- `disabled` - External server, disabled
**Artifact Type:** `Table`
**Columns:** `name`, `server_type`, `port`, `enabled`, `status`, `endpoint`, `binary_debug`, `binary_release`
---
### mcp status
Report health and running state of configured MCP servers via the orchestrator.
```bash
sp plugins mcp status
sp --json plugins mcp status
sp plugins mcp status --detailed
sp plugins mcp status --server content-manager
```
**Flags:**
| `--detailed`, `-d` | `false` | Show detailed output including binary paths |
| `--server` | All | Filter to a specific server by name |
**Output Structure:**
```json
{
"servers": [
{
"name": "filesystem",
"server_type": "internal",
"port": 9001,
"enabled": true,
"running": true,
"health": "healthy",
"pid": 12345,
"binary": "mcp-filesystem",
"release_binary": "exists",
"debug_binary": "exists"
}
],
"summary": {
"total": 3,
"enabled": 2,
"running": 2
}
}
```
**Artifact Type:** `Table`
**Columns:** `name`, `server_type`, `port`, `enabled`, `running`, `health`, `pid`, `endpoint`, `release_binary`, `debug_binary`
---
### mcp validate
Validate connectivity to one or all configured MCP servers with an authenticated handshake. Returns tools count, latency, and server info.
```bash
sp plugins mcp validate <server-name>
sp --json plugins mcp validate filesystem
sp plugins mcp validate database --timeout 30
sp plugins mcp validate --all
sp plugins mcp validate --all --timeout 5
```
**Arguments:**
| `<server>` | Yes* | MCP server name (*not required with `--all`, or in non-interactive mode where all servers are validated) |
**Flags:**
| `--service <name>` | None | Alias for the positional MCP server name (conflicts with the positional) |
| `--all` | `false` | Validate all configured servers |
| `--timeout` | `10` | Connection timeout in seconds |
**Validation Checks:**
- Service is running (checked via database)
- Connection can be established
- MCP protocol handshake succeeds
- Tools are registered
- Latency measurement
An OAuth-gated server is validated by port reachability alone — no token exists
to call `tools/list` with — so `tools_count` is omitted from its result rather
than reported as `0`.
**Output Structure (Single Server):**
```json
{
"results": [
{
"server": "filesystem",
"valid": true,
"health_status": "healthy",
"validation_type": "mcp_validated",
"tools_count": 5,
"latency_ms": 15,
"server_info": {
"name": "filesystem",
"version": "1.0.0",
"protocol_version": "2024-11-05"
},
"issues": [],
"message": "MCP validated with 5 tools"
}
],
"summary": {
"total": 1,
"valid": 1,
"invalid": 0,
"healthy": 1,
"unhealthy": 0
}
}
```
**Health Status Values:**
- `healthy` - Connected and responsive
- `auth_required` - Port responding but OAuth needed
- `unhealthy` - Connection failed or timed out
- `stopped` - Service not running
- `not_found` - Server not in configuration
**Validation Type Values:**
- `mcp_validated` - Full MCP handshake succeeded
- `not_running` - Service is not running
- `timeout` - Connection timed out
- `connection_error` - Failed to connect
- `config_error` - Server not in configuration
- `database_error` - Failed to read service status
**Artifact Type:** `Card`
---
### mcp logs
Tail logs for an MCP server, read from the database by default and falling back to disk files.
```bash
sp plugins mcp logs <server-name>
sp plugins mcp logs filesystem
sp plugins mcp logs filesystem --lines 100
sp plugins mcp logs filesystem --follow
sp plugins mcp logs filesystem --level error
sp plugins mcp logs filesystem --disk
sp plugins mcp logs --logs-dir /custom/path
```
**Arguments:**
| `<server>` | No | MCP server name (shows all MCP logs if not specified) |
**Flags:**
| `--lines`, `-n`, `--tail` | `50` | Number of lines to show |
| `--follow`, `-f` | `false` | Follow log output continuously (disk only) |
| `--disk` | `false` | Force reading from disk files instead of database |
| `--logs-dir` | Profile path | Custom logs directory path |
| `--level` | All | Filter by log level: `debug`, `info`, `warn`, `error` |
**Log Level Filtering:**
- `debug` - Show all log levels
- `info` - Show INFO, WARN, ERROR (exclude DEBUG)
- `warn` - Show WARN and ERROR only
- `error` - Show ERROR only
**Output Structure:**
```json
{
"service": "filesystem",
"source": "database",
"logs": [
"2024-01-15 10:30:00 INFO [mcp-filesystem] Server started on port 9001",
"2024-01-15 10:30:01 INFO [mcp-filesystem] Registered 5 tools"
],
"log_files": []
}
```
**Artifact Type:** `Text`
---
### mcp list-packages
List discovered MCP package names from the registry, for use in build commands.
```bash
sp plugins mcp list-packages
sp --json plugins mcp list-packages
sp plugins mcp list-packages --raw
```
**Flags:**
| `--raw` | Output as a space-separated string in the `raw_packages` field |
**Output Structure:**
```json
{
"packages": [
"mcp-filesystem",
"mcp-database",
"mcp-search"
]
}
```
**Output Structure (with --raw):**
```json
{
"packages": [
"mcp-filesystem",
"mcp-database"
],
"raw_packages": "mcp-filesystem mcp-database"
}
```
**Artifact Type:** `List` (or `CopyPasteText` with `--raw`)
---
### mcp tools
List tools advertised by running MCP servers, optionally with full schemas.
```bash
sp plugins mcp tools
sp --json plugins mcp tools
sp plugins mcp tools --server filesystem
sp plugins mcp tools --detailed
sp plugins mcp tools --schema
sp plugins mcp tools --timeout 60
```
**Flags:**
| `--server`, `-s` | All running | Filter to a specific MCP server |
| `--detailed` | `false` | Show full input/output schemas in JSON output |
| `--schema` | `false` | Display parameter schemas in a readable format |
| `--timeout` | `30` | Timeout in seconds |
**Output Structure:**
```json
{
"tools": [
{
"name": "read_file",
"server": "filesystem",
"description": "Read the contents of a file",
"parameters_count": 1
}
],
"summary": {
"total_tools": 5,
"servers_queried": 1
}
}
```
**Artifact Type:** `Table`
**Columns:** `name`, `server`, `description`, `parameters_count`
---
### mcp call
Invoke a named tool on a running MCP server with JSON arguments and render the result.
```bash
sp plugins mcp call <server> <tool>
sp plugins mcp call systemprompt systemprompt --args '{"command":"core skills list"}'
sp plugins mcp call filesystem read_file -a '{"path":"/etc/hosts"}'
sp plugins mcp call database query --args '{"sql":"SELECT 1"}' --timeout 60
```
**Arguments:**
| `<server>` | Yes (non-interactive) | MCP server name |
| `<tool>` | Yes (non-interactive) | Tool name to execute |
**Flags:**
| `--args`, `-a` | None | Tool arguments as a JSON string |
| `--timeout` | `30` | Timeout in seconds |
**Output Structure:**
```json
{
"server": "filesystem",
"tool": "read_file",
"success": true,
"content": [
{
"kind": "text",
"text": "file contents here"
}
],
"execution_time_ms": 42
}
```
**Artifact Type:** `Card`
---
## Complete MCP Management Flow Example
This flow demonstrates MCP server management:
```bash
# Phase 1: List configured servers
sp --json plugins mcp list
# Phase 2: Check build status
sp --json plugins mcp list-packages
sp build mcp --release
# Phase 3: Check running status
sp --json plugins mcp status
sp --json plugins mcp status --server filesystem
# Phase 4: Validate a specific server with timeout
sp --json plugins mcp validate filesystem --timeout 30
# Phase 5: Validate all servers
sp --json plugins mcp validate --all
# Phase 6: Inspect the tools a server exposes
sp --json plugins mcp tools --server filesystem
# Phase 7: Invoke a tool
sp --json plugins mcp call filesystem read_file -a '{"path":"/etc/hosts"}'
# Phase 8: Check logs with level filtering
sp plugins mcp logs filesystem --lines 20 --level error
# Phase 9: Follow logs in real-time
sp plugins mcp logs filesystem --follow
```
---
## MCP Server Configuration
MCP servers are configured in the services configuration:
```yaml
# services.yaml
mcp_servers:
filesystem:
enabled: true
port: 9001
command: "./target/debug/mcp-filesystem"
binary: "mcp-filesystem"
transport: stdio
args: []
env: {}
oauth:
required: false
database:
enabled: true
port: 9002
command: "./target/debug/mcp-database"
binary: "mcp-database"
transport: stdio
args: []
env:
DATABASE_URL: "${DATABASE_URL}"
oauth:
required: true
```
---
## Troubleshooting MCP Servers
### Server Not Starting
```bash
# Check whether the binary exists
sp --json plugins mcp status --server filesystem
# Look for a null debug/release binary or a not-built status
# Build the server
sp build mcp --server filesystem
# Re-check status
sp --json plugins mcp status --server filesystem
```
### Connection Issues
```bash
# Validate connection with an extended timeout
sp plugins mcp validate filesystem --timeout 30
# Check the validation type in the response
# Check logs for errors
sp plugins mcp logs filesystem --level error --lines 100
```
### Tool Registration Issues
```bash
# Validate and check the tools count. The field is absent when the tool list
# was never enumerated — an OAuth-gated server is probed for reachability only.
# List the tools directly
### Batch Validation
```bash
# Validate all servers at once
sp --json plugins mcp validate --all
# Check the summary
# Find unhealthy servers
---
## Error Handling
### Server Not Found
```bash
sp plugins mcp validate nonexistent
# Error: MCP server 'nonexistent' not found
sp plugins mcp call nonexistent sometool
# Error: MCP server 'nonexistent' not found in configuration
```
### Service Not Running
```bash
sp plugins mcp validate filesystem
# Returns: health_status: "stopped", validation_type: "not_running"
sp plugins mcp call filesystem read_file
# Error: MCP server 'filesystem' is not running
```
### Connection Timeout
```bash
sp plugins mcp validate filesystem --timeout 5
# Returns: health_status: "unhealthy", validation_type: "timeout"
```
### Non-Interactive Mode
```bash
# validate with no server name validates all configured servers
sp --non-interactive plugins mcp validate
# call requires an explicit server and tool
sp --non-interactive plugins mcp call filesystem read_file -a '{"path":"/etc/hosts"}'
```
---
## JSON Output
All commands support the `--json` flag for structured output:
```bash
# Verify JSON is valid
# Extract specific fields
sp --json plugins mcp validate --all | jq '.results[] | select(.valid == false)'
sp --json plugins mcp list-packages | jq '.packages[]'
sp --json plugins mcp tools | jq '.tools[] | {name, server}'
# Check summaries
# Get the raw package list for shell scripts
---
## Integration with Services
MCP servers are started automatically with services:
```bash
# Start all services including MCP
sp infra services start
# Start only MCP servers
sp infra services start --mcp
# Stop MCP servers
sp infra services stop --mcp
```
---