| skill_id | mcp-management |
| name | MCP Server Management |
| description | Manage external MCP server connections to extend Thoth's capabilities |
| version | 1.0.0 |
| author | Thoth Team |
| required_tools | ["list_mcp_servers","add_mcp_server","update_mcp_server","remove_mcp_server","toggle_mcp_server","test_mcp_connection"] |
| tags | ["management","mcp","configuration","tools"] |
MCP Server Management Skill
Overview
This skill provides comprehensive management of external MCP (Model Context Protocol) servers that can extend Thoth's capabilities with additional tools and resources.
What is MCP?
MCP (Model Context Protocol) is a standard protocol that allows AI assistants to connect to external tool servers. By adding MCP servers, you can:
- Access additional tools (filesystem, databases, APIs, etc.)
- Integrate with external services
- Extend Thoth's capabilities without modifying core code
- Connect to custom tool servers you or others have built
Core Capabilities
1. List MCP Servers
View all configured external MCP servers, their connection status, and tool counts.
Example:
Can you show me what MCP servers are configured?
2. Add MCP Server
Add a new external MCP server with stdio, HTTP, or SSE transport.
Example for stdio transport:
Add an MCP server called "my-filesystem" with:
- transport: stdio
- command: npx
- args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/folder"]
- enabled: true
- auto_attach: true
Example for SSE transport:
Add an MCP server called "remote-analysis" with:
- transport: sse
- url: http://localhost:8080/mcp
- enabled: true
- auto_attach: false
3. Update MCP Server
Modify an existing server's configuration.
Example:
Update the "my-filesystem" server to enable auto-attach
4. Remove MCP Server
Remove a server from the configuration (disconnects and detaches tools).
Example:
Remove the "remote-analysis" MCP server
5. Toggle MCP Server
Enable or disable a server without removing it.
Example:
Disable the "my-filesystem" server
6. Test Connection
Test connectivity to a configured MCP server.
Example:
Test the connection to the "my-filesystem" server
Configuration File
All MCP servers are stored in vault/thoth/_thoth/mcps.json. This file serves as the single source of truth and is monitored for changes (hot-reload enabled).
File Format
{
"version": "1.0.0",
"mcpServers": {
"server-id": {
"name": "Server Name",
"enabled": true,
"transport": "stdio|http|sse",
"command": "command-for-stdio",
"args": ["arg1", "arg2"],
"url": "http://url-for-http-or-sse",
"env": {"ENV_VAR": "value"},
"autoAttach": true,
"timeout": 30
}
}
}
Transport Types
stdio (Standard Input/Output)
Best for local command-line tools that communicate via stdin/stdout.
Required fields: command, args
Example: npx-based MCP servers
HTTP
Best for HTTP-based REST APIs.
Required fields: url
Example: http://localhost:8080/mcp
SSE (Server-Sent Events)
Best for streaming responses and real-time updates.
Required fields: url
Example: http://localhost:8080/mcp
Auto-Attach Behavior
When autoAttach: true:
- Tools from the server are automatically attached to all Letta agents
- New agents automatically get these tools
- Disabling the server detaches tools from agents
When autoAttach: false:
- Tools are available but not automatically attached
- Useful for servers with tools you want to use selectively
Hot-Reload
The system watches mcps.json for changes and automatically:
- Connects new servers when added
- Reconnects servers when configuration changes
- Disconnects servers when removed or disabled
- Syncs tool attachments with Letta agents
You can manually edit the file or use the provided tools.
Common MCP Servers
Filesystem Access
{
"filesystem": {
"name": "Filesystem Server",
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
"autoAttach": true,
"timeout": 30
}
}
SQLite Database
{
"sqlite": {
"name": "SQLite Database",
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data.db"],
"autoAttach": true,
"timeout": 30
}
}
GitHub Integration
{
"github": {
"name": "GitHub Server",
"enabled": true,
"transport": "stdio",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {"GITHUB_TOKEN": "your-token"},
"autoAttach": false,
"timeout": 30
}
}
Best Practices
- Start disabled: Add new servers with
enabled: false and test before enabling
- Test connections: Always test connectivity before fully configuring
- Use auto-attach wisely: Only auto-attach tools that are broadly useful
- Set appropriate timeouts: Adjust based on server response times
- Secure credentials: Use environment variables for sensitive data
- Document custom servers: Add clear descriptions for custom MCP servers
Troubleshooting
Server won't connect
- Check the command/URL is correct
- Verify the server is installed and accessible
- Check logs for connection errors
- Test with a longer timeout
Tools not appearing
- Ensure server is enabled
- Check
autoAttach setting
- Verify server connection status
- Check Letta agent tool list
Configuration not updating
- Wait 2-3 seconds for hot-reload
- Check file permissions on
mcps.json
- Verify JSON syntax is valid
- Check server logs for errors
Related Skills
- settings-management: Manage Thoth core settings
- skill-creation-workshop: Create custom skills
References