# Use Your Own MCP Server (https://www.shipfox.io/docs/how-to/author-workflows/use-your-own-mcp-server)

Description: Give an agent step the tools of 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](https://github.com/mongodb-js/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 [#before-you-begin]

* Complete onboarding in [Shipfox](https://app.shipfox.io).
* [Create a secret](https://www.shipfox.io/docs/how-to/set-up-work/secrets-and-variables) 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 [#add-the-mcp-server-to-the-agent-step]

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

```yaml
# 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 [#adapt-it-to-your-workflow]

| To...                                     | Change this                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Use another stdio MCP server              | Copy the `command`, `args`, and `env` of the server from its documentation or from your `.mcp.json` file.                 |
| Use two servers in one step               | Add a second entry under `mcp_servers`. Each entry needs its own name.                                                    |
| Use a server together with an integration | Add `integrations` to the same step. See [Agent integration fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-integration-fields). |
| Run the server in your own image          | Run the job in a container. See [Run a job in a container](https://www.shipfox.io/docs/how-to/author-workflows/run-job-in-container).                |
| Find every field                          | See [MCP server fields](https://www.shipfox.io/docs/reference/workflow-schema#agent-mcp-server-fields).                                              |

## If the step fails before the agent starts [#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.