Use Your Own MCP Server

Use mcp_servers to give an agent step the tools of an MCP server that Shipfox has no integration for. The runner starts the server when the step starts and stops it when the step ends.

In the example, the agent uses mongodb-mcp-server to read a database. For another server, keep the shape of the entry and change the command, the arguments, and the environment variables.

Before you begin

• Complete onboarding in Shipfox.
• Create a secret named MONGO_URI that holds the connection string of the database. Use a database user that can only read.
• Make sure that the database accepts connections from the runner. For MongoDB Atlas, add the public IP address of the runner to the IP access list of the project.

Add the MCP server to the agent step

Create .shipfox/workflows/investigate-slow-queries.yml:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Investigate slow queries
runner: shipfox

triggers:
  manual:
    source: manual

jobs:
  investigate:
    steps:
      - prompt: |
          Find the slowest queries on the orders collection.
          Explain why each one is slow and suggest an index.
          Do not change any data.
        mcp_servers:
          # The agent sees each tool as <name>__<tool>, such as mongodb__find.
          mongodb:
            # The runner starts this program without a shell. Neither
            # command nor args can read workflow expressions.
            command: npx
            args: [-y, mongodb-mcp-server@1.2.0]
            # Values can read secrets. Shipfox masks them in the step log.
            env:
              MDB_MCP_CONNECTION_STRING: ${{ secrets.MONGO_URI }}
              MDB_MCP_READ_ONLY: "true"
            # Optional. Without it, the agent gets every tool of the server.
            include: [find, aggregate, list-collections, explain]

Commit and push the file to the default branch of the project.

Adapt it to your workflow

If the step fails before the agent starts

The step fails with An MCP server is unavailable when the server exits, does not answer within 120 seconds, does not list a tool from include, or lists a tool that the agent cannot use. When the server did not start, the message shows the end of what the server wrote to its error output.

• Check that the command exists on the runner, or in the image of the job container.
• Check the names in include against the tool names in the documentation of the server.
• If a tool name is too long, shorten the name of the server, or leave the tool out of include. Each full tool name has at most 64 characters.