Railway MCP Server

Instructions

Implementation Reference

• src/tools/service.tool.ts:7-29 (registration)

  Registration of the 'service_list' tool using createTool. Includes tool name, formatted description with relations, input schema, and thin handler delegating to serviceService.

  createTool(
    "service_list", // TODO: update this tool to also return the status of the service
    formatToolDescription({
      type: 'API',
      description: "List all services in a specific Railway project",
      bestFor: [
        "Getting an overview of a project's services",
        "Finding service IDs",
        "Checking service status",
      ],
      relations: {
        prerequisites: ["project_list"],
        nextSteps: ["service_info", "deployment_list"],
        related: ["project_info", "variable_list"]
      }
    }),
    {
      projectId: z.string().describe("ID of the project to list services from")
    },
    async ({ projectId }) => {
      return serviceService.listServices(projectId);
    }
  ),

• src/tools/service.tool.ts:24-25 (schema)

  Input schema for service_list tool: requires projectId string.

    projectId: z.string().describe("ID of the project to list services from")
  },

• src/tools/service.tool.ts:26-28 (handler)

  Execution handler for the service_list tool.

  async ({ projectId }) => {
    return serviceService.listServices(projectId);
  }

• src/services/service.service.ts:11-52 (helper)

  Helper method listServices in ServiceService: fetches project services, gets latest deployment status for each, formats a user-friendly list with status and URLs.

    async listServices(projectId: string) {
      try {
        const services = await this.client.services.listServices(projectId);
  
        if (services.length === 0) {
          return createSuccessResponse({
            text: "No services found in this project.",
            data: []
          });
        }
  
        // Get latest deployment status for each service
        const serviceDetails = await Promise.all(services.map(async (service: Service) => {
          try {
            const deployments = await this.client.deployments.listDeployments({
              projectId,
              serviceId: service.id,
              limit: 1
            });
            
            const latestDeployment = deployments[0];
            if (latestDeployment) {
              return `🚀 ${service.name} (ID: ${service.id})
  Status: ${latestDeployment.status}
  URL: ${latestDeployment.url || 'Not deployed'}`;
            }
            
            return `🚀 ${service.name} (ID: ${service.id})
  Status: No deployments`;
          } catch {
            return `🚀 ${service.name} (ID: ${service.id})`;
          }
        }));
  
        return createSuccessResponse({
          text: `Services in project:\n\n${serviceDetails.join('\n\n')}`,
          data: services
        });
      } catch (error) {
        return createErrorResponse(`Error listing services: ${formatError(error)}`);
      }
    }

• src/tools/index.ts:32-36 (registration)

  Final MCP server registration: spreads serviceTools (including service_list) into allTools and calls server.tool for each.

  allTools.forEach((tool) => {
    server.tool(
      ...tool
    );
  });