Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a framework that delivers contextual data to AI clients in real time. It acts as a bridge that provides AI models with the information they need to improve accuracy and relevance. For example, if you’re developing an AI client that conducts code reviews, it may require specific context from your GitHub repository. To provide this context, you can run the GitHub MCP server and have your AI client query the endpoint.

You can run MCP servers locally or as a hosted service. Local servers use STDIO for communication and are limited to a single user, which means they can't be shared. Hosted servers use server-sent events (SSE), so anyone with the server's URL can access them.

Using Blackbird, you can deploy an MCP server in a hosted, non-production environment for testing purposes. This can reduce local resource usage, streamline your workflow, allow for collaboration, and enhance security. This is particularly useful for smaller teams or individuals working in limited environments where running multiple local services can cause performance issues. For larger teams, hosting an MCP server improves security by centralizing key and token management, which is important when working with sensitive data or maintaining security compliance with requirements such as SOC 2.

Use the following procedures and resources in this guide to learn how to host an MCP server in Blackbird and share it with your team.

• Hosting a third-party MCP server in Blackbird using the CLI
• Hosting a third-party MCP server in Blackbird using Visual Studio Code
• Example - Hosting an MCP server in Blackbird

Hosting a third-party MCP server in Blackbird using the CLI

You can host a third-party MCP server in Blackbird using the Blackbird CLI. The MCP catalog offers several options to fit different use cases. In this procedure, you'll browse the catalog, select a server, deploy it in your environment, and export the connection details to use in a compatible client (e.g., VS Code or Cursor).

Note: The following procedure provides key arguments and flags related to the CLI commands, but you can find more information and examples in the Blackbird CLI.

Prerequisites

• You installed the Blackbird CLI. For more information, see Getting started with the Blackbird CLI.
• You installed Docker and it's actively running. For more information, see Get Docker.

To host an MCP server using the CLI:

1. View the MCP server catalog to determine which server you want to deploy. This procedure uses the GitHub MCP server.

   The catalog includes the server names, tags, descriptions, and required parameters. Note the parameters for the server you want to deploy (e.g., GITHUB_PERSONAL_ACCESS_TOKEN for GitHub). You’ll input these parameters in the next step.

2. Run an MCP server deployment.

   Key arguments and flags include:

   • <name> – The name you want to use for your server.
   • --image – The name of the third-party MCP server you want to use (e.g., github).
   • --secure – Whether you want to use an API key to secure your server endpoint (e.g., true).

     Note: If you don’t secure your instance, the endpoint will be publicly available.

   • --param – The required parameters from the previous step (e.g., GITHUB_PERSONAL_ACCESS_TOKEN=your-token). When the deployment completes, a URL displays.

3. Make an HTTP request to the URL generated by the deployment to verify the connection.

   Note: If you secured your instance, you'll need to provide the API Key header in the request.

   Your MCP server is now running in Blackbird.

4. Export connection details in a structured format that you can add to your MCP client.

   Key arguments and flags include:

   • --name – The name of one or more MCP servers for which you want to export details (e.g., github).
   • --path – The location where you want to save the exported file (e.g., ./config.json).
   • --style – The style of the configuration file you want to export (e.g, vscode).

Next steps

Now that you have an MCP server running in Blackbird and your connection details, you can add your MCP server to an application of your choice. For an example implementation, see Add an MCP server in the VS Code documentation.

Hosting a third-party MCP server in Blackbird using Visual Studio Code

You can use the Visual Studio Code (VS Code) integration to host a third-party MCP server in Blackbird. Our MCP catalog offers several options to fit different use cases. In this procedure, you'll browse the catalog, select a server, and deploy it in your environment.

Prerequisites

• You installed Docker and it's actively running. For more information, see Get Docker.
• You installed the Visual Studio Code extension. For more information, see Visual Studio Code.

To host an MCP server using VS Code:

1. Make sure the extension is running in VS Code.

2. In the side bar, expand MCP Catalog to view available servers. Hover over a server to view a description. This procedure uses the GitHub MCP server.

3. Hover over the server you want to deploy and select the rocket icon to launch it.

4. The input box prompts you for each required parameter (e.g., server name, whether to secure the instance, GitHub personal access token, etc.).

   Note: If you don’t secure your instance, the endpoint will be publicly available.

5. When the deployment completes, expand MCP Deployments in the side bar to view your deployed server and its endpoint.

6. Make an HTTP request to the URL generated by the deployment to verify the connection.

   Note: If you secured your instance, you'll need to provide the API Key header in the request.

   Your MCP server is now running in Blackbird.

Next steps

Now that you have an MCP server running in Blackbird, you can add your MCP server to an application of your choice. For an example implementation, see Add an MCP server in the VS Code documentation.

Example - Hosting an MCP server in Blackbird

The steps in the following example workflow use the GitHub MCP client and Cursor integrated development environment (IDE). However, you can adapt them to use other MCP servers or MCP-compatible IDEs or clients as needed.

Prerequisites

Before following the example workflow, ensure you meet the following requirements:

• You installed the Blackbird CLI. For more information, see Getting started with the Blackbird CLI.
• You installed Docker and it's actively running. For more information, see Get Docker.
• You installed the Cursor MCP client. For more information, see Download Cursor.

Hosting an MCP server in Blackbird

After you meet the prerequisites, use the following procedure to:

• Use a Dockerfile to deploy the GitHub MCP server in Blackbird.

• Run the hosted GitHub MCP server.

• Connect the Cursor LLM to the hosted GitHub MCP server.

  To host a GitHub MCP server:

1. Create a Dockerfile with the following content:
2. Create an .env file alongside the Dockerfile with the following entries. Replace <BLACKBIRD_ENV_HOST> with the unique hostname of your Blackbird environment. To find this, you can either check the URL of any existing mock or deployment instance in Blackbird or run the following command from the CLI: blackbird instance list

   Important: You can adapt this Dockerfile to run any prebuilt MCP server. Currently, the GitHub MCP server uses STDIO, which doesn't support remote HTTP connections. This example uses SuperGateway to transform MCP servers from STDIO to SSE.

3. In the same directory as your Dockerfile and .env file, run the following command using the Blackbird CLI:After the deployment completes, you'll see a Blackbird URL for your hosted GitHub MCP server.
4. Locate or create the MCP server configuration file in Cursor, which is typically called mcp.json. Add your hosted GitHub MCP server URL from Blackbird to the config and add /sse to the URL:
5. In Cursor, navigate to Settings>MCP to verify that the MCP server exists and enable it. Your chat conversations with the Cursor LLM will now use the remote GitHub MCP server.