awslabs.aws-appsync-mcp-server 0.1.12

An AWS Labs Model Context Protocol (MCP) server for AWS AppSync Service capabilities

AWS AppSync MCP Server

A Model Context Protocol (MCP) server for AWS AppSync that enables AI assistants to manage and interact with backend APIs.

Overview

The AWS AppSync MCP Server simplifies the management of APIs by providing capabilities to create graphQL APIs, data sources, resolvers, and other AppSync resources. This allows for streamlined API development and easier integration with AWS backend services through natural language interactions.

Features

• API Management: Create and configure AppSync APIs with various authentication types
• GraphQL API Creation: Set up GraphQL APIs with schema definitions and authentication
• API Key Management: Generate and manage API keys for authentication
• API Caching: Configure caching for improved API performance
• Data Source Management: Connect APIs to various AWS backend services (DynamoDB, Lambda, RDS, etc.)
• Function Management: Create and manage AppSync functions for complex business logic
• Channel Namespace Management: Set up real-time subscriptions with channel namespaces
• Domain Name Management: Configure custom domain names for APIs
• Resolver Management: Create resolvers to connect GraphQL fields to data sources
• Schema Management: Define and update GraphQL schemas
• Read-Only Mode: Enable an optional security mode that restricts all operations to read-only, preventing any modifications

Prerequisites

1. Install uv from Astral or the GitHub README
2. Install Python using uv python install 3.10
3. Set up AWS credentials with access to AWS AppSync
   • You need an AWS account with AWS AppSync enabled
   • Configure AWS credentials with aws configure or environment variables
   • Ensure your IAM role/user has permissions to use AWS AppSync

Setup

Installation

Kiro	Cursor	VS Code

Configuration

Add the MCP server in your MCP client configuration (e.g., for Kiro, edit ~/.kiro/settings/mcp.json)

Using AWS Profiles

For standard AWS profile-based authentication:

{
  "mcpServers": {
    "awslabs.aws-appsync-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-appsync-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Using Temporary Credentials

For temporary credentials (such as those from AWS STS, IAM roles, or federation):

{
  "mcpServers": {
    "awslabs.aws-appsync-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.aws-appsync-mcp-server@latest"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-temporary-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-temporary-secret-key", // pragma: allowlist secret
        "AWS_SESSION_TOKEN": "your-session-token",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Enabling Write Operations using --allow-write

Enables tools that create or modify resources in the user's AWS account. When this flag is not enabled, the server runs in read-only mode that only allows read operations. This enhances security by preventing any modifications to AppSync resources. In read-only mode:

• Read operations work normally
• Write operations (create_api, create_graphql_api, create_datasource, etc.) are blocked and return a permission error

This mode is particularly useful for:

• Demonstration environments
• Security-sensitive applications
• Integration with public-facing AI assistants
• Protecting production APIs from unintended modifications

Example:

{
  "mcpServers": {
    "awslabs.aws-appsync-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.aws-appsync-mcp-server@latest",
        "--allow-write"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

Docker Configuration

After building with docker build -t awslabs/aws-appsync-mcp-server .:

{
  "mcpServers": {
    "awslabs.aws-appsync-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "awslabs/aws-appsync-mcp-server:latest"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Environment Variables

• AWS_PROFILE: AWS CLI profile to use for credentials
• AWS_REGION: AWS region to use (default: us-east-1)
• AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY: Explicit AWS credentials (alternative to AWS_PROFILE)
• AWS_SESSION_TOKEN: Session token for temporary credentials (used with AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY)
• FASTMCP_LOG_LEVEL: Logging level (ERROR, WARNING, INFO, DEBUG)

Tools

The server exposes the following tools through the MCP interface:

create_api

Creates a new AppSync API with the given configuration.

create_api(name: str) -> dict

create_graphql_api

Creates a new GraphQL API with authentication and other configuration options.

create_graphql_api(
    name: str,
    authentication_type: str = "API_KEY"
) -> dict

create_api_key

Creates an API key for authentication with an AppSync API.

create_api_key(
    api_id: str,
    description: str = None,
    expires: int = None
) -> dict

create_api_cache

Creates and configures caching for an AppSync API to improve performance.

create_api_cache(
    api_id: str,
    ttl: int = 3600,
    api_caching_behavior: str = "FULL_REQUEST_CACHING",
    type: str = "SMALL"
) -> dict

create_datasource

Creates a data source to connect the API to backend services like DynamoDB, Lambda, or RDS.

create_datasource(
    api_id: str,
    name: str,
    type: str,
    service_role_arn: str = None,
    dynamodb_config: dict = None,
    lambda_config: dict = None,
    elasticsearch_config: dict = None,
    relational_database_config: dict = None
) -> dict

create_function

Creates an AppSync function for reusable business logic.

create_function(
    api_id: str,
    name: str,
    data_source_name: str,
    function_version: str = "2018-05-29",
    request_mapping_template: str = None,
    response_mapping_template: str = None
) -> dict

create_channel_namespace

Creates a channel namespace for real-time subscriptions.

create_channel_namespace(
    api_id: str,
    name: str,
    publish_auth_modes: list = None,
    subscribe_auth_modes: list = None
) -> dict

create_domain_name

Creates a custom domain name for an AppSync API.

create_domain_name(
    domain_name: str,
    certificate_arn: str,
    description: str = None
) -> dict

create_resolver

Creates a resolver to connect GraphQL fields to data sources.

create_resolver(
    api_id: str,
    type_name: str,
    field_name: str,
    data_source_name: str = None,
    request_mapping_template: str = None,
    response_mapping_template: str = None,
    kind: str = "UNIT"
) -> dict

create_schema

Creates or updates the GraphQL schema for an API.

create_schema(
    api_id: str,
    definition: str
) -> dict

Usage Examples

Prompt	Description
Create a GraphQL API named "blog-api" with API key authentication	Creates a new GraphQL API with the specified name and authentication type
Add a GraphQL schema with a Post type with an id primary key, content and author fields	Creates or updates the API schema with custom types and fields
Create a DynamoDB data source for my API connecting to the "posts" table	Sets up a data source to connect the API to a DynamoDB table
Create a resolver for the "getPosts" query field	Creates a resolver to handle GraphQL query execution
Set up API caching with 1 hour TTL for better performance	Configures caching to improve API response times
Create an API key that expires in 30 days	Generates an API key with a specific expiration date
Create a Lambda data source for custom business logic	Sets up a data source to connect the API to AWS Lambda functions

AWS AppSync Resources

This server uses the AWS AppSync service APIs for:

• GraphQL API creation and management
• Data source configuration (DynamoDB, Lambda, RDS, etc.)
• Resolver creation and management
• Schema definition and updates
• API key and authentication management
• Caching configuration
• Real-time subscription setup

Security Considerations

• Use AWS profiles for credential management
• Use IAM policies to restrict access to only the required AWS AppSync resources
• Use temporary credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN) from AWS STS for enhanced security
• Implement AWS IAM roles with temporary credentials for applications and services
• Regularly rotate credentials and use the shortest practical expiration time for temporary credentials
• Be aware of AWS AppSync service quotas and limits
• Use the --allow-write flag judiciously and only when write operations are necessary

⚠️ IMPORTANT: YOU ARE RESPONSIBLE FOR YOUR AGENTS

You are solely responsible for the actions and permissions of agents using the MCP server.

• By default, the MCP server operates in read-only mode.
• To enable write access, you must explicitly configure the MCP with the necessary IAM permissions and use "--allow-write" flag to enable create operations on AWS AppSync using the MCP server.
• Always follow the principle of least privilege—grant only the permissions necessary for the agent to function.
• If enabling write operations, we recommend you take a backup of your data and carefully validate any instructions generated by your LLM before execution. Perform such actions during a scheduled maintenance window for your application.
• With AWS AppSync MCP Server, we recommend exercising caution when integrating it into automated workflows.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.