Adding Smithy targets to your Gateway

Smithy is a language for defining services and SDKs that works well with Gateway. Smithy models provide a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services.

Built-in Smithy Models

Gateway provides built-in Smithy models for popular AWS services. When you create a Smithy target without specifying a model, it defaults to the DynamoDB model:

# Create a Smithy target with default DynamoDB model
smithy_target = agentcore_client.create_gateway_target(
    gatewayIdentifier=gateway["gatewayId"],
    name="DynamoDBTarget",
    targetConfiguration={"mcp": {"smithyModel": {}}},  # Empty - uses default DynamoDB model
    credentialProviderConfigurations=[{"credentialProviderType": "GATEWAY_IAM_ROLE"}]
)
        

You can find Smithy API models for hundreds of AWS services in the AWS API Models repository. Popular services include:

• DynamoDB (default)

• S3

• Lambda

• EC2

• RDS

To add a Smithy target, you need:

• A Smithy model in JSON AST format

• Optional authentication configuration for accessing the service

You can provide the Smithy model in two ways:

• Inline as a JSON string

• As a reference to an S3 object

Understanding Smithy Model Targets

Smithy model targets connect your Gateway to services defined using Smithy models, such as AWS services like DynamoDB, S3, and more. The Gateway translates incoming MCP requests into API calls to these services and handles the response formatting.

Key components of Smithy model targets include:

• Smithy Model: The Smithy model definition that describes the service API

• Credential Provider: Configuration for how the Gateway authenticates with the service

Required Permissions

For Smithy model targets that access AWS services, your Gateway's execution role needs permissions to access those services. For example, for a DynamoDB target, your execution role needs permissions to perform DynamoDB operations:

JSON

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dynamodb:GetItem",
        "dynamodb:PutItem",
        "dynamodb:UpdateItem",
        "dynamodb:DeleteItem",
        "dynamodb:Query",
        "dynamodb:Scan"
      ],
      "Resource": "arn:aws:dynamodb:*:*:table/*"
    }
  ]
}
      

Smithy Model Types

AgentCore Gateway supports built-in AWS service models only. Smithy models are restricted to AWS services and custom Smithy models for non-AWS services are not supported.

AgentCore Gateway provides built-in Smithy models for common AWS services via an AWS provided S3 bucket that hosts the Smithy files. You can pass the Smithy file URIs to the create target API.

When you create a Smithy model target without specifying a custom model in the AgentCoreSDK, the Gateway will use the built-in DynamoDB model.

Here's an example of creating a Smithy model target for DynamoDB:

# Create a Smithy model target for DynamoDB
dynamodb_target = gateway_client.create_mcp_gateway_target(
    gateway=gateway,
    target_type="smithyModel",
    target_name="DynamoDBTarget",
    target_description="Target for DynamoDB operations"
)
              

With this target, your Gateway will expose DynamoDB operations as tools that can be invoked through the MCP interface.

Smithy Feature Support

The following table outlines the Smithy features that are supported and unsupported by Gateway:

Smithy Feature Support

Supported Features	Unsupported Features
Service Definitions Service structure definitions based on Smithy specifications Operation definitions with input/output shapes Resource definitions Trait shapes	Endpoint Rules Endpoint creation rule sets Runtime endpoint determination based on conditions Complex URL parameters beyond simple {region} substitution
Protocol Support RestJson protocol Standard HTTP request/response patterns	Protocol Support RestXml protocol JsonRpc protocol AwsQuery protocol Ec2Query protocol Custom protocols
Data Types Primitive types (string, integer, boolean, float, double) Complex types (structures, lists, maps) Timestamp handling Blob data types	Authentication Multiple egress authentication types for specific APIs Complex authentication schemes requiring runtime decisions
HTTP Bindings Basic HTTP method bindings Simple path parameter bindings Query parameter bindings Header bindings for simple cases	Operations Streaming operations Operations requiring custom protocol implementations

When using Smithy models with Gateway, be aware of the following limitations:

• Maximum model size: 10MB

• Only JSON protocol bindings are fully supported

• Only RestJson protocol is supported

• Complex endpoint creation rule sets are not supported

• Only simple URL parameters like {region} are supported

Example of a supported Smithy model for a weather service:

namespace example.weather

use aws.protocols#restJson1
use smithy.framework#ValidationException

/// Weather service for retrieving weather information
@restJson1
service WeatherService {
    version: "1.0.0",
    operations: [GetCurrentWeather]
}

/// Get current weather for a location
@http(method: "GET", uri: "/weather")
operation GetCurrentWeather {
    input: GetCurrentWeatherInput,
    output: GetCurrentWeatherOutput,
    errors: [ValidationException]
}

structure GetCurrentWeatherInput {
    /// City name or coordinates
    @required
    @httpQuery("location")
    location: String,

    /// Units of measurement (metric or imperial)
    @httpQuery("units")
    units: Units = metric
}

structure GetCurrentWeatherOutput {
    /// Location name
    location: String,

    /// Current temperature
    temperature: Float,

    /// Weather conditions description
    conditions: String,

    /// Humidity percentage
    humidity: Float
}

enum Units {
    metric
    imperial
}
        

Example of an unsupported endpoint rules configuration:

@endpointRuleSet({
  "rules": [
    {
      "conditions": [{"fn": "booleanEquals", "argv": [{"ref": "UseFIPS"}, true]}],
      "endpoint": {"url": "https://weather-fips.{Region}.example.com"}
    },
    {
      "endpoint": {"url": "https://weather.{Region}.example.com"}
    }
  ]
})
        

Creating a Smithy target

You can add a Smithy target to your Gateway using one of the following methods:

Console

To add a Smithy target to an existing gateway

1. Open the AgentCore console at https://console.aws.amazon.com/bedrock-agentcore/home#.

2. Choose Gateways.

3. Select the gateway to which you want to add a target.

4. Choose the Targets tab.

5. Choose Add target.

6. Enter a Target name.

7. (Optional) Provide an optional Target description.

8. For Target type, choose REST API.

9. Choose Smithy schema.

10. For Smithy schema, choose to either use a built-in AWS service model or provide a custom Smithy model via S3 or inline.

11. In the Outbound authentication section, configure authentication for accessing the service:

    1. For Authentication type, choose GATEWAY_IAM_ROLE.

12. Choose Add target.

AgentCore SDK

You can add a Smithy model target using the AgentCore SDK:

from bedrock_agentcore_starter_toolkit.operations.gateway.client import GatewayClient

# Initialize the Gateway client
gateway_client = GatewayClient(region_name="us-west-2")

# Create a Smithy model target for a built-in AWS service (e.g., DynamoDB)
smithy_target = gateway_client.create_mcp_gateway_target(
    gateway=gateway,
    target_type="smithyModel"
)

# Or create a Smithy model target with a custom model
custom_smithy_target = gateway_client.create_mcp_gateway_target(
    gateway=gateway, 
    target_type="smithyModel",
    target_payload={
        "s3": {
            "uri": "s3://your-bucket/path/to/smithy-model.json"
        }
    }
)
            

Boto3

The following Python code shows how to add a Smithy model target using boto3 (AWS SDK for Python):

import boto3

# Create the agentcore client
agentcore_client = boto3.client('bedrock-agentcore-control')

# Create a Smithy model target
target = agentcore_client.create_gateway_target(
    gatewayIdentifier="your-gateway-id",
    name="DynamoDBTarget",
    targetConfiguration={
        "mcp": {
            "smithyModel": {
                "s3": {
                    "uri": "s3://your-bucket/path/to/smithy-model.json",
                    "bucketOwnerAccountId": "123456789012"
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE"
        }
    ]
)
            

API

Use the CreateGatewayTarget operation to add a Smithy model target to your Gateway:

PUT /gateways/abc123def4/targets/ HTTP/1.1
Content-Type: application/json

{
  "gatewayIdentifier": "abc123def4",
  "name": "DynamoDBTarget",
  "targetConfiguration": {
    "mcp": {
      "smithyModel": {
        "s3": {
          "uri": "s3://your-bucket/path/to/smithy-model.json",
          "bucketOwnerAccountId": "123456789012"
        }
      }
    }
  },
  "credentialProviderConfigurations": [
    {
      "credentialProviderType": "GATEWAY_IAM_ROLE"
    }
  ]
}
            

Updating a Smithy Model Target

You can update an existing Smithy model target using the UpdateGatewayTarget API:

updated_target = agentcore_client.update_gateway_target(
    gatewayIdentifier="your-gateway-id",
    targetId="your-target-id",
    name="UpdatedDynamoDBTarget",
    targetConfiguration={
        "mcp": {
            "smithyModel": {
                "s3": {
                    "uri": "s3://your-bucket/path/to/updated-smithy-model.json"
                }
            }
        }
    },
    credentialProviderConfigurations=[
        {
            "credentialProviderType": "GATEWAY_IAM_ROLE"
        }
    ]
)
        

Advanced Smithy Model Target Configurations

Inline Smithy Models

For small Smithy models, you can provide the model inline when creating the target:

target = gateway_client.create_mcp_gateway_target(
    gateway=gateway,
    target_type="smithyModel",
    target_payload={
        "inlinePayload": """
        {
            "smithy": "1.0",
            "shapes": {
                "com.example#MyService": {
                    "type": "service",
                    "version": "2023-01-01",
                    "operations": [
                        {
                            "target": "com.example#GetData"
                        }
                    ]
                },
                "com.example#GetData": {
                    "type": "operation",
                    "input": {
                        "target": "com.example#GetDataInput"
                    },
                    "output": {
                        "target": "com.example#GetDataOutput"
                    }
                },
                "com.example#GetDataInput": {
                    "type": "structure",
                    "members": {
                        "id": {
                            "target": "smithy.api#String",
                            "required": true
                        }
                    }
                },
                "com.example#GetDataOutput": {
                    "type": "structure",
                    "members": {
                        "data": {
                            "target": "smithy.api#String"
                        }
                    }
                }
            }
        }
        """
    }
)