Skip to main content

# Connecting MCP Servers

Learn how to connect different types of MCP servers to your vMCP instance.

## Overview​

MCP servers can use different transport types:

- stdio - Command-line programs (most common)
- HTTP - REST API servers
- SSE - Server-Sent Events

## Navigate to Connections​

1. Open http://localhost:8000
2. Click "Connections" in the navigation menu
3. You'll see all your configured MCP servers

## Adding a Stdio MCP Server​

Stdio servers are command-line programs that communicate via stdin/stdout.

### Example: Filesystem MCP​

The filesystem MCP provides file operations.

Configuration:

    {
      "name": "filesystem",
      "description": "Local filesystem access",
      "transport_type": "stdio",
      "config": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/path/to/workspace"
        ]
      }
    }

Provides:

- `list_directory` - List files in a directory
- `read_file` - Read file contents
- `write_file` - Write to a file
- `search_files` - Search for files

### Example: GitHub MCP​

Access GitHub repositories and issues.

Configuration:

    {
      "name": "github",
      "description": "GitHub integration",
      "transport_type": "stdio",
      "config": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-github"
        ],
        "env": {
          "GITHUB_TOKEN": "your_token_here"
        }
      }
    }

Provides:

- `create_issue` - Create GitHub issue
- `list_issues` - List repository issues
- `get_file_contents` - Get file from repo
- `push_files` - Push changes to repo

### Example: PostgreSQL MCP​

Database access via MCP.

Configuration:

    {
      "name": "postgres",
      "description": "PostgreSQL database access",
      "transport_type": "stdio",
      "config": {
        "command": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-postgres"
        ],
        "env": {
          "DATABASE_URL": "postgresql://user:pass@localhost/db"
        }
      }
    }

## Adding an HTTP MCP Server​

HTTP servers expose MCP protocol over REST endpoints.

Configuration:

    {
      "name": "api-server",
      "description": "Custom API MCP server",
      "transport_type": "http",
      "config": {
        "url": "https://api.example.com/mcp",
        "headers": {
          "Authorization": "Bearer your-token"
        }
      }
    }

## Adding an SSE MCP Server​

Server-Sent Events for real-time updates.

Configuration:

    {
      "name": "realtime-server",
      "description": "Real-time MCP server",
      "transport_type": "sse",
      "config": {
        "url": "https://sse.example.com/mcp/events"
      }
    }

## Testing the Connection​

After adding a server:

1. Click the "Connect" button on the server card
2. Status will change to "Connected" if successful
3. Click "Test" to verify functionality

### Status Indicators​

- Connected (Green) - Server is active and responding
- Disconnected (Gray) - Server is not connected
- Auth Required (Yellow) - OAuth or authentication needed
- Error (Red) - Connection failed

## Managing Environment Variables​

For sensitive data like API keys:

### Option 1: Environment File​

Create a `.env` file in the backend directory:

    GITHUB_TOKEN=ghp_your_token_here
    DATABASE_URL=postgresql://user:pass@localhost/db
    OPENAI_API_KEY=sk-your-key-here

Reference in server config:

    {
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }

### Option 2: Direct Configuration​

Store directly in the server config (less secure, not recommended for production):

    {
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }

## Popular MCP Servers​

### Official Servers​

From `@modelcontextprotocol`:

- `server-filesystem` - File system operations
- `server-github` - GitHub integration
- `server-postgres` - PostgreSQL database
- `server-sqlite` - SQLite database
- `server-memory` - Key-value memory storage

### Community Servers​

- AWS - S3, Lambda, EC2 operations
- Google Cloud - GCS, BigQuery, Cloud Functions
- Slack - Messaging and channel management
- Jira - Issue tracking
- Confluence - Documentation access

## Building Custom MCP Servers​

You can build custom servers using FastMCP:

    from fastmcp import FastMCP

    mcp = FastMCP("My Custom Server")

    @mcp.tool()
    def my_tool(param: str) -> str:
        """My custom tool"""
        return f"Result: {param}"

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

Run your custom server:

    {
      "name": "custom-server",
      "transport_type": "stdio",
      "config": {
        "command": "python",
        "args": ["my_server.py"]
      }
    }

## Troubleshooting​

### Connection Fails​

1. Check the command is correct and installed
2. Verify environment variables are set
3. Check logs in the Stats page
4. Ensure required permissions (file access, API keys, etc.)

### Server Not Responding​

1. Click "Disconnect" then "Connect" to restart
2. Check if the process is running: `ps aux | grep [server-name]`
3. Review error logs in backend console

### Tools Not Appearing​

1. Ensure server is "Connected"
2. Click "Refresh" on the Connections page
3. Check server capabilities in the API response

## Next Steps​

- Creating Your First vMCP
- Variable Substitution
- Configuration Guide