Skip to content

Configuring the Catalog MCP Backend Plugin#

This guide covers the configuration options for the Catalog MCP backend plugin.

Prerequisites Configuration#

Catalog Configuration#

Ensure the Backstage Catalog is properly configured:

# app-config.yaml
catalog:
  import:
    entityFilename: catalog-info.yaml
  rules:
    - allow: [Component, System, API, Resource, Location, User, Group, Domain, Template]
  providers:
    # Add your catalog providers here

Authentication Configuration#

The plugin uses the Backstage backend authentication system to make authenticated requests to the catalog API.

Backend Authentication#

Ensure backend authentication is configured:

backend:
  auth:
    keys:
      - secret: ${BACKEND_SECRET}

Service-to-Service Authentication#

The plugin automatically uses service credentials for catalog API calls. No additional configuration is required.

MCP Actions Configuration#

The plugin automatically registers all 5 MCP actions. No additional configuration is required for basic functionality.

Available Actions#

  1. get_entities_by_owner - Query entities by owner
  2. get_entities_by_annotation - Search by annotations
  3. get_entity_types_for_kind - Discover entity types
  4. get_all_entities_by_kind_and_type - Filter by kind and type
  5. get_entities_with_custom_query - Flexible custom queries

Best Practices#

Query Optimization#

  1. Use Field Selection
  2. When using get_entities_with_custom_query, specify fields to reduce response size
  3. Only request the data you need

  4. Example: fields: "kind,metadata.name,spec.owner"

  5. Filter Appropriately

  6. Use specific filters to reduce result sets
  7. Combine multiple filters for precise queries

  8. Example: filter: "kind=Component,spec.type=service"

  9. Owner Queries

  10. Use group references for team-based queries
  11. Cache results when querying the same owner repeatedly
  12. Consider using custom queries for complex owner filters

Entity Discovery#

  1. Type Discovery
  2. Use get_entity_types_for_kind before querying by type
  3. Cache type lists for better performance

  4. Validate types before filtering

  5. Annotation Searches

  6. Use key-only searches for discovery
  7. Use key+value searches for precise matches

  8. Consider indexing commonly-searched annotations

  9. Custom Queries

  10. Start with simple filters and add complexity gradually
  11. Test queries with field selection for performance
  12. Monitor query response times

Security#

  1. Authentication
  2. Always enable authentication
  3. Use strong backend secrets
  4. Rotate secrets regularly

  5. Monitor authentication failures

  6. Authorization

  7. Respect catalog permissions
  8. Implement read-only access where appropriate
  9. Log all query operations

  10. Monitor unusual query patterns

  11. Logging and Monitoring

  12. Enable backend logging
  13. Monitor [CATALOG MCP] log entries
  14. Track API errors and failures
  15. Set up alerts for high query volumes

Error Handling#

The plugin provides comprehensive error logging:

[CATALOG MCP] Fetching entities by owner: http://localhost:7007/api/catalog/entities/by-query?filter=spec.owner=...
[CATALOG MCP] Fetching entities by annotation: http://localhost:7007/api/catalog/entities/by-query?filter=...
[CATALOG MCP] API Error: { ... }

Enable debug logging to troubleshoot issues:

backend:
  log:
    level: debug

Advanced Configuration#

Custom Backend URL#

If your catalog runs on a different URL, update the configuration:

backend:
  baseUrl: http://your-backend:7007

Timeout Configuration#

Adjust timeout values for large catalogs:

backend:
  reading:
    timeout: 60000  # 60 seconds for large queries

CORS Configuration#

If accessing from different origins:

backend:
  cors:
    origin: http://localhost:3000
    methods: [GET, POST, PUT, DELETE, PATCH]
    credentials: true

Integration with Catalog Providers#

Entity Ingestion#

Ensure entities are being ingested properly:

catalog:
  providers:
    github:
      organization: 'my-org'
      catalogPath: '/catalog-info.yaml'
      filters:
        branch: 'main'
    kubernetes:
      clusters:
        - name: 'production'
          url: 'https://k8s.example.com'
          authProvider: 'serviceAccount'

Metadata Annotations#

Configure standard annotations for better searchability:

# Example catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  annotations:
    github.com/project-slug: 'my-org/my-service'
    backstage.io/techdocs-ref: 'dir:.'
    backstage.io/source-location: 'url:https://github.com/my-org/my-service'
spec:
  type: service
  owner: group:default/platform-team

Query Examples#

Basic Owner Query#

Find all entities owned by a team:

{
  "action": "get_entities_by_owner",
  "input": {
    "owner": "group:default/platform-team"
  }
}

Find entities with GitHub integration:

{
  "action": "get_entities_by_annotation",
  "input": {
    "annotation": "github.com/project-slug"
  }
}

Type Discovery#

Discover all component types:

{
  "action": "get_entity_types_for_kind",
  "input": {
    "kind": "Component"
  }
}

Filtered Query#

Find all service components:

{
  "action": "get_all_entities_by_kind_and_type",
  "input": {
    "kind": "Component",
    "type": "service"
  }
}

Complex Custom Query#

Find specific entities with field selection:

{
  "action": "get_entities_with_custom_query",
  "input": {
    "filter": "kind=Component,spec.type=service,spec.owner=group:default/platform",
    "fields": "kind,metadata.name,metadata.namespace,spec.type,spec.owner"
  }
}

Troubleshooting#

Common Configuration Issues#

  1. Catalog Not Accessible
  2. Symptom: Connection errors or 404 responses
  3. Solution: Verify catalog is running and accessible

  4. Check: curl http://localhost:7007/api/catalog/entities

  5. No Entities Returned

  6. Symptom: Empty results for valid queries
  7. Solution: Check catalog has entities ingested

  8. Check: View catalog in Backstage UI

  9. Authentication Failures

  10. Symptom: 401 or 403 errors
  11. Solution: Verify backend authentication is configured

  12. Check: Backend secret is set correctly

  13. Invalid Filter Format

  14. Symptom: Query parsing errors
  15. Solution: Use comma-separated filters without spaces

  16. Example: "kind=Component,spec.type=service" (not "kind = Component, spec.type = service")

  17. Large Response Times

  18. Symptom: Slow query responses
  19. Solution: Use field selection to reduce data
  20. Solution: Add more specific filters
  21. Solution: Increase backend timeout

Debug Mode#

Enable detailed logging:

backend:
  log:
    level: debug
    format: json

Check logs for: - Query URLs being constructed - Filter parameters being applied - Response sizes and timing - Error details with full context

Performance Tuning#

For Large Catalogs (1000+ entities)#

  1. Use Field Selection 

    {
  "fields": "kind,metadata.name,spec.type"
}

  2. Add Specific Filters 

    {
  "filter": "kind=Component,spec.type=service,metadata.namespace=production"
}

  3. Increase Timeouts 

    backend:
  reading:
    timeout: 120000

  4. Consider Caching

  5. Cache common queries at the application level
  6. Use catalog response caching
  7. Implement query result memoization

Next Steps#

After configuration: 1. Test queries using MCP actions 2. Monitor performance and error rates 3. Adjust timeouts and filters as needed 4. Set up logging and monitoring 5. Document common queries for your team