Roadie MCP AI Servers (Beta)

Introduction

Roadie exposes a number of Model Context Protocol Servers (MCP) via our authenticated API that can provide AI tools like agents and LLMs with structured data to answer complex questions about your catalog and powerful workflow capabilities using the scaffolder.

Available MCP Servers

Roadie currently provides four MCP servers that enable AI assistants to interact with your Backstage catalog:

• API Docs Query Server - Discover and retrieve API documentation and specifications
  • https://api.roadie.so/api/mcp/v1/api-docs-query
• Scaffolder Server - Find, validate, and execute Backstage scaffolder templates
  • https://api.roadie.so/api/mcp/v1/scaffolder-use
• Rich Catalog Entity Server - Access catalog entity data, relationships, and documentation
  • https://api.roadie.so/api/mcp/v1/rich-catalog-entity
• Tech Insights Facts Server - Access operational metrics, security data, and compliance information
  • https://api.roadie.so/api/mcp/v1/tech-insights-facts

Prerequisites

• Roadie tenant with populated catalog
• Active Roadie API token
• AI assistant or MCP client configured to use Roadie’s MCP servers

Tool Integration Setup

Setting up MCP Servers in Popular AI Tools

{
  "servers": {
    "roadie-api-docs": {
      "url": "https://api.roadie.so/api/mcp/v1/api-docs-query",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-scaffolder": {
      "url": "https://api.roadie.so/api/mcp/v1/scaffolder-use",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-catalog": {
      "url": "https://api.roadie.so/api/mcp/v1/rich-catalog-entity",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-insights": {
      "url": "https://api.roadie.so/api/mcp/v1/tech-insights-facts",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    }
  }
}

{
  "mcpServers": {
    "roadie-api-docs": {
      "url": "https://api.roadie.so/api/mcp/v1/api-docs-query",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-scaffolder": {
      "url": "https://api.roadie.so/api/mcp/v1/scaffolder-use",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-catalog": {
      "url": "https://api.roadie.so/api/mcp/v1/rich-catalog-entity",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-insights": {
      "url": "https://api.roadie.so/api/mcp/v1/tech-insights-facts",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    }
  }
}

{
  "mcpServers": {
    "roadie-api-docs": {
      "url": "https://api.roadie.so/api/mcp/v1/api-docs-query",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-scaffolder": {
      "url": "https://api.roadie.so/api/mcp/v1/scaffolder-use",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-catalog": {
      "url": "https://api.roadie.so/api/mcp/v1/rich-catalog-entity",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    },
    "roadie-insights": {
      "url": "https://api.roadie.so/api/mcp/v1/tech-insights-facts",
      "headers": {
        "Authorization": "Bearer <roadie_api_token>"
      }
    }
  }
}

Authentication Setup

You will need an API token for your user to connect with these MCP servers. See API Token docs here. You may need an admin user to provide you with a Roadie API Token.

Troubleshooting Setup

Common Issues:

1. Authentication Errors:

   • Verify your API token is correct and not expired
   • Check that the token has appropriate permissions

2. Connection Failures:

   • Verify network connectivity to your Roadie instance
   • Check that the MCP API endpoints are accessible

3. Permission Denied:

   • Review your API token permissions
   • Contact your Roadie administrator for access

4. MCP Server Configuration Issues:

   • Verify the URL format is correct: https://api.roadie.so/api/mcp/v1/<server-name>
   • Check that all required headers are included in the configuration
   • Ensure environment variables are properly set

Testing Connection:

# Test API connectivity and MCP endpoint
curl -H "Authorization: Bearer $ROADIE_API_TOKEN" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     https://api.roadie.so/api/mcp/v1/rich-catalog-entity

# Test catalog API access
curl -H "Authorization: Bearer $ROADIE_API_TOKEN" \
     -H "Content-Type: application/json" \
     https://api.roadie.so/api/catalog/entities

Best Practices

API Discovery

• Start with broad search terms and refine based on results

Template Execution

• Always validate inputs before execution to catch errors early
• Provide clear, descriptive names for generated projects

Error Handling

• Check validation results before proceeding with template execution
• Monitor task status for long-running templates
• Review error messages for troubleshooting guidance
• Ensure proper permissions are in place before execution

Support and Troubleshooting

Common Issues

Authentication Errors

• Verify your Roadie API credentials are configured correctly
• Ensure your MCP client is properly authenticated

Permission Denied

• Check that you have the necessary permissions for catalog access and scaffolder execution
• Contact your Roadie administrator if you need additional permissions

Template Execution Failures

• Use validate-template-values to check inputs before execution
• Review template requirements and ensure all parameters are provided
• Check get-scaffolder-task for detailed error information

For additional support, please refer to the Roadie documentation or contact our support team.