Railway MCP Server

Instructions

Implementation Reference

• src/tools/domain.tool.ts:60-68 (handler)

  The main handler function for the "domain_create" MCP tool. It extracts parameters from the tool call and delegates to the domainService.createServiceDomain method.

  async ({ environmentId, serviceId, domain, suffix, targetPort }) => {
    return domainService.createServiceDomain({
      environmentId,
      serviceId,
      domain,
      suffix,
      targetPort
    });
  }

• src/tools/domain.tool.ts:53-59 (schema)

  Zod schema defining the input parameters for the domain_create tool.

  {
    environmentId: z.string().describe("ID of the environment"),
    serviceId: z.string().describe("ID of the service"),
    domain: z.string().optional().describe("Custom domain name (optional, as railway will generate one for you and is generally better to leave it up to railway to generate one. There's usually no need to specify this and there are no use cases for overriding it.)"),
    suffix: z.string().optional().describe("Suffix for the domain (optional, railway will generate one for you and is generally better to leave it up to railway to generate one.)"),
    targetPort: z.number().optional().describe("Target port for the domain (optional, as railway will use the default port for the service and detect it automatically.)"),
  },

• src/tools/domain.tool.ts:32-69 (registration)

  The domain_create tool is defined and registered to the domainTools array using createTool, which includes name, description, schema, and handler.

  createTool(
    "domain_create",
    formatToolDescription({
      type: 'API',
      description: "Create a new domain for a service",
      bestFor: [
        "Setting up custom domains",
        "Configuring service endpoints",
        "Adding HTTPS endpoints"
      ],
      notFor: [
        "TCP proxy setup (use tcp_proxy_create)",
        "Internal service communication"
      ],
      relations: {
        prerequisites: ["service_list", "domain_check"],
        nextSteps: ["domain_update"],
        alternatives: ["tcp_proxy_create"],
        related: ["service_info", "domain_list"]
      }
    }),
    {
      environmentId: z.string().describe("ID of the environment"),
      serviceId: z.string().describe("ID of the service"),
      domain: z.string().optional().describe("Custom domain name (optional, as railway will generate one for you and is generally better to leave it up to railway to generate one. There's usually no need to specify this and there are no use cases for overriding it.)"),
      suffix: z.string().optional().describe("Suffix for the domain (optional, railway will generate one for you and is generally better to leave it up to railway to generate one.)"),
      targetPort: z.number().optional().describe("Target port for the domain (optional, as railway will use the default port for the service and detect it automatically.)"),
    },
    async ({ environmentId, serviceId, domain, suffix, targetPort }) => {
      return domainService.createServiceDomain({
        environmentId,
        serviceId,
        domain,
        suffix,
        targetPort
      });
    }
  ),

• src/tools/index.ts:16-37 (registration)

  Final registration of all tools, including domainTools containing domain_create, to the MCP server via server.tool().

  export function registerAllTools(server: McpServer) {
    // Collect all tools
    const allTools = [
      ...databaseTools,
      ...deploymentTools,
      ...domainTools,
      ...projectTools,
      ...serviceTools,
      ...tcpProxyTools,
      ...variableTools,
      ...configTools,
      ...volumeTools,
      ...templateTools,
    ] as Tool[];
  
    // Register each tool with the server
    allTools.forEach((tool) => {
      server.tool(
        ...tool
      );
    });
  } 

• src/services/domain.service.ts:16-34 (helper)

  Helper service method that handles domain creation logic, including availability check and API call via repository.

  async createServiceDomain(input: ServiceDomainCreateInput): Promise<CallToolResult> {
    try {
      // Check domain availability if a domain is specified
      if (input.domain) {
        const availability = await this.client.domains.serviceDomainAvailable(input.domain);
        if (!availability.available) {
          return createErrorResponse(`Domain unavailable: ${availability.message}`);
        }
      }
      
      const domain = await this.client.domains.serviceDomainCreate(input);
      return createSuccessResponse({
        text: `Domain created successfully: ${domain.domain} (ID: ${domain.id}, Port: ${domain.targetPort || 'default'})`,
        data: domain
      });
    } catch (error) {
      return createErrorResponse(`Error creating domain: ${formatError(error)}`);
    }
  }