Tavro Agent Catalog on AWS

This repository provides Tavro's open-source reference implementation of the Agent Metadata Specification (AMS) under the Tavro Agent Catalog. It includes AWS CDK infrastructure setup, deployment steps, and database schema initialization scripts to help teams deploy and run the Tavro Agent Catalog in their own AWS environment.

Enterprise Platform: tavro.ai

---

Table of Contents

• Overview
• Prerequisites
• Getting Started
• Configuration
• Deployment
• Post-Deployment
• Database Initialization
• Azure Connector
• Teardown
• Contributing

---

Overview

The Tavro Agent Catalog provides:

• AWS CDK infrastructure for deploying a fully managed agent catalog
• FastAPI + MCP server for agent registration and risk classification
• Catalog connectors (Azure, Copilot) for syncing agent metadata
• DDL schema scripts for a structured agent data model across raw, core, curated, and risk layers
• Sample agent cards and AI use case cards across banking, insurance, pharma, utilities, and more

---

Prerequisites

Before starting, ensure the following are in place:

Required tools:

• Docker — must be installed and running before any CDK commands
• Python 3.8+ — with pip available
• Node.js — required for AWS CDK CLI
• AWS CLI — configured with appropriate credentials
• AWS CDK CLI — install once globally:

npm install -g aws-cdk

AWS permissions: Your IAM user/role must have sufficient permissions to create S3 buckets, Glue databases, Lambda functions, ECS services, ALBs, and IAM roles.

---

Getting Started

1. Clone the Repository

git clone https://github.com/TavroOrg/tavro_aws.git
cd tavro_aws

2. Install Python Dependencies

# macOS / Linux
pip3 install -r requirements.txt

# Windows
pip install -r requirements.txt

# Alternative (if above fails)
python -m pip install -r requirements.txt

3. Set Up GitHub Authentication

The MCP server uses GitHub OAuth for authentication. Before deployment, register a GitHub OAuth App and obtain your credentials:

Follow the setup guide at: https://gofastmcp.com/integrations/github

You'll need:

• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET

---

Configuration

Create config.yaml

Copy the example file and fill in your values:

cp config.yaml.example config.yaml

Minimum required values:

region: us-east-2
aws_access_key_id: &access_key YOUR_ACCESS_KEY
aws_secret_access_key: &secret_key YOUR_SECRET_KEY

S3:
  bucket: &bucket_name your-bucket-name          # lowercase, hyphens/dots only

secret_manager:
  keys:
    - OPENAI_API_KEY: "sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    - GITHUB_CLIENT_ID: "your_client_id"
    - GITHUB_CLIENT_SECRET: "your_client_secret"

Region change note: If you change the region in config.yaml, make sure you update the same region for your subnet availability configuration as well.

subnets:
  public:
    - name: catalog_subnet1
      cidr: 10.0.1.0/24
      availability_zone: us-east-2a  ------> Update here
      map_public_ip: true
    - name: catalog_subnet2
      cidr: 10.0.2.0/24
      availability_zone: us-east-2b  ------> Update here
      map_public_ip: false

S3 bucket naming: Must contain only lowercase letters, numbers, hyphens (-), and dots (.).

Recommendation: Do not change other values in config.yaml unless you understand the downstream effects (see notes below).

---

Pre-Deployment Code Updates

Before deploying, make the following code-level updates:

1. Set the MCP Server Root URL

File: fast-api-mcp/mcp_server/server.py

# Comment out the environment variable line:
# ROOT_URL = f"http://{os.getenv('mcp_host')}:{os.getenv('mcp_port')}"

# Replace with your hosted domain:
ROOT_URL = "https://your-hosted-domain.com"

2. Set the Risk Classification API URL

File: fast-api-mcp/risk_agents/agent_extractor.py

Locate the send_payload_async function and update the URL:

"https://your-hosted-domain.com/classify-risk"

3. Set the Lambda API URL

File: lambda/agent_records_inserted/index.py

Update the API_URL variable at the top of the file with your API Gateway or service URL.

4. Ensure Shell Scripts Use LF Line Endings

The following scripts must use LF (Unix) line endings, not CRLF, for correct execution in Docker/AWS Linux environments:

• fast-api-mcp/start_fastapi.sh
• fast-api-mcp/start_mcp.sh

In VS Code: open each file → click CRLF in the status bar → select LF → save.

5. Update AWS Region References (if changing region)

If you deploy to a region other than us-east-2, update the region in:

• fast-api-mcp/db/db_functions.py
• fast-api-mcp/risk_agents/agent_extractor.py
• fast-api-mcp/utils/aws_secrets.py

Ensure these match the region value in config.yaml.

6. Update Lambda Configs if Renaming Database or Workgroup

If you change the database name or workgroup name in config.yaml, also update the corresponding variable names at the top of:

• lambda/agent_records_inserted/index.py
• lambda/curated_agent_card/index.py

---

Deployment

Bootstrap (One-Time Setup per Account/Region)

CDK bootstrap creates the staging infrastructure CDK needs to deploy. This is a one-time step per AWS account and region:

cdk bootstrap aws://YOUR_ACCOUNT_ID/YOUR_REGION
# Example:
cdk bootstrap aws://123456789012/us-east-2

Skip this step if your account/region has already been bootstrapped by you or your AWS administrator.

Reference: AWS CDK Bootstrapping Docs

---

Preview Changes (Optional)

Review what will be created or modified before deploying:

# macOS / Linux
cdk diff --app "python3 app.py"

# Windows
cdk diff --app "python app.py"

This will show changes to S3 buckets, Glue databases, CDK helper resources, and permissions.

---

Deploy

# macOS / Linux
cdk deploy --app "python3 app.py"

# Windows
cdk deploy --app "python app.py"

During deployment, CDK may prompt:

Do you wish to deploy these changes (y/n)?

Enter y to confirm. This prompt appears when security-sensitive changes (e.g., IAM policy updates) are detected.

What gets created:

• S3 bucket and folder structure (as defined in config.yaml)
• AWS Glue Data Catalog databases (raw, core, curated layers)
• Lambda functions
• ECS services (FastAPI + MCP server containers)
• Application Load Balancer
• CDK deployment helper resources and IAM roles

---

Post-Deployment

1. Configure the Application Load Balancer (ALB)

1. Go to EC2 -> Load Balancers in the AWS Console.
2. Select the ALB created by the CDK stack.
3. Under the Listeners tab, add an HTTPS listener on port 443 and attach an SSL/TLS certificate via AWS Certificate Manager (ACM).
4. In the HTTPS (443) listener rules, add the following path-based rules:

rules:
  - priority: 1
    conditions:
      - field: path-pattern
        values:
          - /mcp
    target_group: mcp

  - priority: 2
    conditions:
      - field: path-pattern
        values:
          - /.well-known/*
    target_group: mcp

  - priority: 3
    conditions:
      - field: path-pattern
        values:
          - /authorize
    target_group: mcp

  - priority: 4
    conditions:
      - field: path-pattern
        values:
          - /register
    target_group: mcp

  - priority: 5
    conditions:
      - field: path-pattern
        values:
          - /consent
    target_group: mcp

  - priority: 6
    conditions:
      - field: path-pattern
        values:
          - /auth/*
    target_group: mcp

  - priority: 9
    conditions:
      - field: path-pattern
        values:
          - /temporal/*
    target_group: temporal

---

Database Initialization

Run the DDL scripts to create all required Athena/Glue schema objects:

# macOS / Linux
python3 -m scripts.run_ddl

# Windows
python -m scripts.run_ddl

This creates tables across the raw, core, curated, and risk_management layers defined in the ddl/ directory.

---

Azure Connector

After DDL initialization, you can sync agent metadata from Azure.

1. Add your Azure credentials to config.yaml under catalog_connector.azure
2. Run the connector:

# macOS / Linux
python3 -m run_connectors

# Windows
python -m run_connectors

---

Teardown

To remove all deployed infrastructure:

1. Go to AWS Console → CloudFormation → Stacks
2. Select the stack created by this project
3. Choose Delete and confirm
4. Wait for DELETE_COMPLETE status

Important: Always delete through CloudFormation, not by manually removing individual resources (S3, Glue, etc.). Manual deletion breaks CloudFormation state and can leave orphaned resources.

---

Contributing

Contributions and feedback are welcome. If you encounter issues, have ideas for improvements, or want to propose new capabilities:

• Open an issue on GitHub
• Submit a pull request

Help us strengthen the Tavro Agent Catalog for the broader community.