Understanding MCP Servers and the Official Registry

The Model Context Protocol (MCP) defines a standard for how different software components, particularly those dealing with context and data, can communicate and interoperate. Installing an MCP server involves deploying a service that adheres to this protocol, making it discoverable and usable by other applications within an ecosystem. The official MCP registry, located at https://registry.modelcontextprotocol.io, serves as a central repository where these servers are published and can be discovered.

SAFi (Serverless Application Framework Interface) is a tool designed to streamline the deployment and management of such applications. Crucially, SAFi comes pre-packaged with the necessary utilities to handle MCP tool installations. This includes its own integrated registry search functionality, which queries the official MCP registry for available MCP servers.

This guide will walk you through the process of installing an MCP server, focusing on leveraging SAFi's capabilities for searching and deploying from the official registry. We will cover the steps for both Dockerized environments and bare-metal installations.

Diagram illustrating the MCP server discovery process via SAFi and the official registry

Searching for MCP Servers

Before you can install an MCP server, you need to find one that meets your requirements. SAFi simplifies this discovery process through its command-line interface. The primary script used for registry interactions is safi_mcp.py, located within the scripts directory of your SAFi installation.

To search for a specific MCP server, you use the search command followed by the name of the vendor or service you are looking for. For instance, if you want to check if Smartsheet has published an MCP server, you would execute the following command.

Using Docker

If you are running SAFi within a Docker environment, you can access the safi_mcp.py script via the docker compose exec command. This allows you to run the script within the running container where SAFi is installed.

docker compose exec app python scripts/safi_mcp.py search smartsheet

This command will execute the Python script inside the container named 'app' and perform a search for 'smartsheet' in the official MCP registry. The output will indicate whether a server matching the search term was found.

On Bare Metal

For users who have installed SAFi directly on a physical or virtual machine (bare metal), the process is slightly different. You first need to navigate to your SAFi installation directory and activate the Python virtual environment. This ensures that the script can access all of SAFi's dependencies.

First, change your directory to the SAFi installation path, which is typically /var/www/safi:

cd /var/www/safi

Next, activate the virtual environment. The command for this is:

source venv/bin/activate

Once the virtual environment is active, your command prompt will change to prepend (venv), indicating that the environment is correctly set up. If you see this change, the environment activation was successful. Skipping this step will result in Python being unable to locate SAFi's required libraries, leading to script failure.

With the virtual environment activated, you can then run the search script:

python3 scripts/safi_mcp.py search smartsheet

This command performs the same registry search as the Docker version but directly on your system.

Installing an MCP Server

Once you have identified an MCP server of interest through the search command, the next step is to install it. SAFi provides an install command for this purpose, which handles downloading and setting up the server based on the registry information.

Docker Installation

To install an MCP server using Docker, you will again use the docker compose exec command:

docker compose exec app python scripts/safi_mcp.py install smartsheet

This command tells SAFi to find the 'smartsheet' MCP server in the registry and initiate its installation process within the Docker environment. SAFi will manage the necessary container setup, networking, and configuration based on the server's definition in the registry.

Bare Metal Installation

For bare-metal installations, ensure your virtual environment is activated as described previously. Then, execute the install command:

python3 scripts/safi_mcp.py install smartsheet

This command will download and configure the 'smartsheet' MCP server directly on your host machine, integrating it with your local environment.

Verifying the Installation

After the installation command completes, it's crucial to verify that the MCP server is running correctly and is accessible. SAFi offers a status command to check the operational state of installed MCP servers.

Checking Server Status

Use the status command, again via docker compose exec for Dockerized environments or directly for bare metal, to confirm the installation.

Docker:

docker compose exec app python scripts/safi_mcp.py status smartsheet

Bare Metal (with venv activated):

python3 scripts/safi_mcp.py status smartsheet

The output of the status command should indicate whether the 'smartsheet' MCP server is running, its version, and any other relevant operational details. Successful verification means your MCP server is ready for use.

Troubleshooting Common Issues

While SAFi aims to simplify MCP server installation, issues can arise. The most common problem encountered is related to the Python virtual environment not being activated correctly for bare-metal installations.

Virtual Environment Errors: If you receive errors about missing dependencies or Python modules when running scripts on bare metal, the first step is to re-verify that you have activated the virtual environment using source venv/bin/activate. Ensure your prompt shows (venv). If you are in a different directory, you might need to adjust the path to the venv directory.

Docker Connectivity Issues: For Docker installations, ensure your Docker daemon is running and that your docker-compose.yml file is correctly configured. Network issues between containers or between the host and containers can also prevent the script from executing or the server from starting. Check Docker logs for more detailed error messages.

Registry Access Problems: If the search or install commands fail to find servers, verify that your internet connection is stable and that the official MCP registry URL (https://registry.modelcontextprotocol.io) is accessible from your environment. Firewall rules could also be a factor.

By following these steps, you can effectively install and manage MCP servers from the official registry using the SAFi tool, ensuring seamless integration of context-aware services into your applications.