@aws/nx-plugin-mcp 0.119.0 → 0.121.0

package/docs/guides/py-agent.mdx

@@ -0,0 +1,483 @@
+---
+title: Python Agent
+description: Generate a Python Agent for building AI agents with tools and deploy to Amazon Bedrock AgentCore Runtime
+generator: py#agent
+---
+
+import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import Infrastructure from '@components/infrastructure.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import Drawer from '@components/drawer.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Generate a Python [Strands Agent](https://strandsagents.com/) for building AI agents with tools, and optionally deploy it to [Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/). By default, the generator uses [FastAPI](https://fastapi.tiangolo.com/) to expose an HTTP server. Alternatively, you can choose the [Agent-to-Agent (A2A)](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-a2a.html) protocol for interoperability with other A2A-compatible agents, or the [AG-UI](https://docs.ag-ui.com/) protocol for direct frontend integration via [CopilotKit](https://docs.copilotkit.ai/aws-strands).
+
+## What is Strands?
+
+[Strands](https://strandsagents.com/docs/user-guide/quickstart/overview/) is a lightweight, production-ready Python framework for building AI agents. Key features include:
+
+- **Lightweight and customizable**: Simple agent loop that gets out of your way
+- **Production ready**: Full observability, tracing, and deployment options for scale
+- **Model and provider agnostic**: Supports many different models from various providers
+- **Community-driven tools**: Powerful set of community-contributed tools
+- **Multi-agent support**: Advanced techniques like agent teams and autonomous agents
+- **Flexible interaction modes**: Conversational, streaming, and non-streaming support
+
+## Usage
+
+### Generate an Agent
+
+You can generate a Python Agent in two ways:
+
+<RunGenerator generator="py#agent" />
+
+:::tip[Project Prerequisite]
+First use the <Link path="/guides/python-project">`py#project`</Link> generator to create a project to add your Agent to.
+:::
+
+### Options
+
+<GeneratorParameters generator="py#agent" />
+
+## Generator Output
+
+The generator will add the following files to your existing Python project. The files generated depend on the chosen `protocol`:
+
+<OptionFilter when={{ protocol: 'HTTP' }} description="FastAPI HTTP server layout">
+### HTTP Protocol (default)
+
+<FileTree>
+  - your-project/
+    - your_module/
+      - agent/ (or custom name if specified)
+        - \_\_init\_\_.py Python package initialization
+        - init.py FastAPI application setup with CORS and error handling middleware
+        - agent.py Main agent definition with sample tools
+        - main.py FastAPI entry point for Bedrock AgentCore Runtime
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - pyproject.toml Updated with Strands dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'A2A' }} description="Strands A2A server layout">
+### A2A Protocol
+
+The entry point uses the [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) instead of FastAPI:
+
+<FileTree>
+  - your-project/
+    - your_module/
+      - agent/ (or custom name if specified)
+        - \_\_init\_\_.py Python package initialization
+        - agent.py Main agent definition with sample tools
+        - main.py A2A server entry point
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - pyproject.toml Updated with Strands dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'AG-UI' }} description="AG-UI / CopilotKit server layout">
+### AG-UI Protocol
+
+The entry point uses the [ag-ui-strands](https://docs.ag-ui.com/) integration, which exposes your agent via the AG-UI protocol for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/aws-strands):
+
+<FileTree>
+  - your-project/
+    - your_module/
+      - agent/ (or custom name if specified)
+        - \_\_init\_\_.py Python package initialization
+        - agent.py Main agent definition with sample tools
+        - main.py AG-UI server entry point using ag-ui-strands
+        - Dockerfile Entry point for hosting your agent (excluded when `computeType` is set to `None`)
+    - pyproject.toml Updated with Strands and AG-UI dependencies
+    - project.json Updated with agent serve targets
+</FileTree>
+
+:::tip[Connect to a React website]
+AG-UI agents can be connected to a React frontend using the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which will set up [CopilotKit](https://docs.copilotkit.ai/aws-strands) components for a rich chat experience.
+:::
+</OptionFilter>
+
+### Infrastructure
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="shared-constructs" />
+
+For deploying your Agent, the following files are generated:
+
+<Infrastructure>
+<Fragment slot="cdk">
+<FileTree>
+  - packages/common/constructs/src
+    - app
+      - agents
+        - \<project-name>
+          - \<project-name>.ts CDK construct for deploying your agent
+</FileTree>
+</Fragment>
+<Fragment slot="terraform">
+<FileTree>
+  - packages/common/terraform/src
+    - app
+      - agents
+        - \<project-name>
+          - \<project-name>.tf Module for deploying your agent
+    - core
+      - agent-core
+        - runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
+</FileTree>
+</Fragment>
+</Infrastructure>
+</OptionFilter>
+
+<OptionFilter when={{ computeType: 'None' }} description="No infrastructure is vended for computeType=None">
+If you selected `None` for `computeType`, no CDK constructs or Terraform modules are generated — the Agent can only be run locally. The `auth` option is ignored in this mode since there is no hosted endpoint to authenticate.
+</OptionFilter>
+
+#### Architecture
+
+<Snippet name="agent/architecture" />
+
+## Working with Your Agent
+
+### Adding Tools
+
+Tools are functions that the AI agent can call to perform actions. The Strands framework uses a simple decorator-based approach for defining tools.
+
+You can add new tools in the `agent.py` file:
+
+```python
+from strands import Agent, tool
+
+@tool
+def calculate_sum(numbers: list[int]) -> int:
+    """Calculate the sum of a list of numbers"""
+    return sum(numbers)
+
+@tool
+def get_weather(city: str) -> str:
+    """Get weather information for a city"""
+    # Your weather API integration here
+    return f"Weather in {city}: Sunny, 25°C"
+
+# Add tools to your agent
+agent = Agent(
+    system_prompt="You are a helpful assistant with access to various tools.",
+    tools=[calculate_sum, get_weather],
+)
+```
+
+The Strands framework automatically handles:
+- Type validation based on your function's type hints
+- JSON schema generation for tool calling
+- Error handling and response formatting
+
+### Using Pre-built Tools
+
+Strands provides a collection of pre-built tools through the `strands-tools` package:
+
+```python
+from strands_tools import current_time, http_request, file_read
+
+agent = Agent(
+    system_prompt="You are a helpful assistant.",
+    tools=[current_time, http_request, file_read],
+)
+```
+
+### Model Configuration
+
+By default, Strands agents use Claude 4 Sonnet, but you can customize the model provider. See the [Strands documentation on model providers](https://strandsagents.com/docs/user-guide/concepts/model-providers/) for configuration options:
+
+```python
+from strands import Agent
+from strands.models import BedrockModel
+
+# Create a BedrockModel
+bedrock_model = BedrockModel(
+    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
+    region_name="us-west-2",
+    temperature=0.3,
+)
+
+agent = Agent(model=bedrock_model)
+```
+
+### Consuming MCP Servers
+
+You can [add tools from MCP servers](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/) to your Strands agent.
+
+For consuming MCP Servers which you have created using the <Link path="/guides/py-mcp-server">`py#mcp-server`</Link> or <Link path="/guides/ts-mcp-server">`ts#mcp-server`</Link> generators you can make use of the <Link path="/guides/connection/py-agent-mcp">`connection` generator</Link>.
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/py-agent-mcp">`connection` generator guide</Link> for details about how the connection is set up.
+
+For other MCP servers, please refer to the [Strands Documentation](https://strandsagents.com/docs/user-guide/concepts/tools/mcp-tools/).
+
+### More
+
+For a more in-depth guide to writing Strands agents, refer to the [Strands documentation](https://strandsagents.com/docs/user-guide/quickstart/overview/).
+
+## Protocol
+
+Your agent's server protocol determines how it communicates. All options are served by [FastAPI](https://fastapi.tiangolo.com/) — the entry point differs:
+
+- **HTTP** (default): A standard FastAPI server with a custom `/invocations` endpoint, CORS, and streaming. Best for custom client integrations.
+- **A2A**: The [Strands A2A Server](https://strandsagents.com/docs/user-guide/concepts/multi-agent/agent-to-agent) mounted onto a FastAPI app. Best when your agent needs to be discoverable and invokable by other A2A-compatible agents.
+- **AG-UI**: The [ag-ui-strands](https://docs.ag-ui.com/) integration, which exposes the [AG-UI protocol](https://docs.ag-ui.com/) over SSE. Best for direct frontend integration with [CopilotKit](https://docs.copilotkit.ai/aws-strands) in a React website.
+
+All protocols expose `/ping` for the AgentCore runtime health check contract. A2A agents listen on port `9000`; HTTP and AG-UI agents listen on port `8080`. The generated Dockerfile and infrastructure are configured for you.
+
+<OptionFilter when={{ protocol: 'HTTP' }} description="FastAPI HTTP server details">
+## FastAPI Server (HTTP protocol)
+
+The generated HTTP server includes:
+- FastAPI application setup with CORS middleware
+- Error handling middleware
+- OpenAPI schema generation
+- Health check endpoint (`/ping`)
+- Agent invocation endpoint (`/invocations`)
+
+### Customizing Invoke Inputs and Outputs with Pydantic
+
+The agent's invocation endpoint uses [Pydantic](https://docs.pydantic.dev/) models to define and validate the request and response schemas. You can customize these models in `main.py` to match your agent's requirements.
+
+#### Defining Input Models
+
+The default `InvokeInput` model accepts a message.
+
+```python
+from pydantic import BaseModel
+
+class InvokeInput(BaseModel):
+    message: str
+```
+
+You can extend this model to include any additional fields your agent needs.
+
+The session ID is extracted from the `x-amzn-bedrock-agentcore-runtime-session-id` HTTP header, consistent with the [Bedrock AgentCore Runtime session contract](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html). If the header is not provided, a random UUID is generated as a fallback.
+
+:::caution[Code Organization]
+You will likely want to abstract some or all of the session ID from the caller if users are to invoke your agent directly. For example, you may use the authenticated user ID as part of the session ID.
+
+It is also worth noting that depending on your use case you may need to implement authorization for sessions, for example ensuring that users may only access their own sessions and not those of other users.
+:::
+
+#### Defining Output Models
+
+For streaming responses, the generator provides `JsonStreamingResponse` which automatically serializes Pydantic models to JSON Lines format (`application/jsonl`). This format is compatible with OpenAPI 3.2's streaming specification and works seamlessly with the generated TypeScript client.
+
+By default, the agent yields `StreamChunk` objects containing the agent's response text:
+
+```python
+class StreamChunk(BaseModel):
+    content: str
+```
+
+You can customise the `StreamChunk` model to suit your needs:
+
+```python
+from pydantic import BaseModel
+
+class StreamChunk(BaseModel):
+    content: str
+    timestamp: str
+    token_count: int
+```
+
+:::note[FastAPI Streaming Limitation]
+Note that since FastAPI does not currently support generating an OpenAPI specification for streaming responses, we must explicitly set the response model for each streaming operation, ie:
+
+```python
+@app.post(
+    "/invocations",
+    response_class=JsonStreamingResponse,
+    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
+)
+async def invoke(input: InvokeInput) -> JsonStreamingResponse:
+    return JsonStreamingResponse(handle_invoke(input))
+```
+:::
+
+There is an [open feature request for native support in FastAPI](https://github.com/fastapi/fastapi/discussions/14362).
+</OptionFilter>
+
+## Bedrock AgentCore Python SDK
+
+The generator includes a dependency on the [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python) for the `PingStatus` constants. If desired, it is straightforward to use `BedrockAgentCoreApp` instead of FastAPI, however note that type-safety is lost.
+
+You can find more details about the SDK's capabilities in the [documentation here](https://aws.github.io/bedrock-agentcore-starter-toolkit/user-guide/runtime/quickstart.html).
+
+:::note[Infrastructure as Code]
+Since the generator vends CDK or Terraform infrastructure which manages deploying your agent, you do not need to utilise the `bedrock-agentcore-starter-toolkit` which the docs mention for deploying your agent.
+:::
+
+<OptionFilter when={{ protocol: 'A2A' }} description="A2A server details">
+## A2A Server (A2A protocol)
+
+The generated `main.py` mounts `A2AServer.to_fastapi_app()` onto a parent FastAPI app that also exposes `/ping`. When deployed to AgentCore, the entry point resolves the runtime's public ARN from AppConfig and advertises it in the agent card.
+
+Most users will not need to modify this file — edit `agent.py` to change tools or the system prompt. The A2A server populates the agent card (`/.well-known/agent-card.json`) from the `Agent` constructor's `name` and `description`.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'AG-UI' }} description="AG-UI / CopilotKit server details">
+## AG-UI Server (AG-UI protocol)
+
+The generated `main.py` wraps your Strands `Agent` in an `ag_ui_strands.StrandsAgent` and creates a FastAPI app via `create_strands_app()`. The resulting app exposes a single POST endpoint that streams [AG-UI](https://docs.ag-ui.com/) events over Server-Sent Events (SSE), as well as `/ping` for the AgentCore runtime health check.
+
+Most users will not need to modify this file — edit `agent.py` to change tools or the system prompt.
+
+:::tip[Connecting to a React website]
+AG-UI agents are designed to be consumed directly by a frontend. Use the <Link path="/guides/connection/react-agui">`connection` generator</Link> to wire your React website up to the agent with a [CopilotKit](https://docs.copilotkit.ai/aws-strands) provider and [AG-UI HttpAgent](https://docs.ag-ui.com/) client.
+:::
+</OptionFilter>
+
+## Running Your Agent
+
+### Local Development
+
+The generator configures a target named `<your-agent-name>-serve`, which starts your Agent locally for development and testing.
+
+<NxCommands commands={['agent-serve your-project']} />
+
+This command uses `uv run` to execute your Agent using the [Bedrock AgentCore Python SDK](https://github.com/aws/bedrock-agentcore-sdk-python).
+
+### Chat with Your Agent
+
+The generator configures a `<your-agent-name>-chat` Nx target that depends on `<your-agent-name>-serve-local`. Running it starts the agent locally and drops you into an interactive terminal chat:
+
+<NxCommands commands={['run your-project:agent-chat']} />
+
+For **HTTP** agents, the generator also emits:
+
+- `scripts/<your-agent-name>_openapi.py` — a small script that exports the agent's OpenAPI spec
+- An `<your-agent-name>-openapi` Nx target that runs it
+- An `<your-agent-name>-generate-client` Nx target that produces a type-safe TypeScript client under `scripts/<your-agent-name>/generated/`
+- `scripts/<your-agent-name>/chat.ts` — a thin wrapper around the generated client
+
+When you customize the agent's input shape (e.g. add new fields to `InvokeInput`), update `chat.ts` to pass the new fields when invoking the agent and the rest works automatically.
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment details">
+## Deploying Your Agent to Bedrock AgentCore Runtime
+
+<Snippet name="agent/bedrock-deployment" parentHeading="Deploying Your Agent to Bedrock AgentCore Runtime" />
+
+### Bundle and Docker Targets
+
+In order to build your Agent for Bedrock AgentCore Runtime, a `bundle` target is added to your project, which:
+
+- Exports your Python dependencies to a `requirements.txt` file using `uv export`
+- Installs dependencies for the target platform (`aarch64-manylinux_2_28`) using `uv pip install`
+
+A `docker` target specific to your Agent is also added, which copies the `Dockerfile` and bundled artifacts into a docker context directory. This co-locates the `Dockerfile` with the built output, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
+
+### Observability
+
+Your agent is automatically configured with observability using the [AWS Distro for Open Telemetry](https://aws.amazon.com/otel/) (ADOT), by configuring auto-instrumentation in your `Dockerfile`.
+
+You can find traces in the CloudWatch AWS Console, by selecting "GenAI Observability" in the menu. Note that for traces to be populated you will need to enable [Transaction Search](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Transaction-Search.html).
+
+For more details, refer to the [AgentCore documentation on observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html).
+</OptionFilter>
+
+## Invoking your Agent
+
+<OptionFilter when={{ protocol: 'HTTP' }} description="FastAPI HTTP invocation details">
+### Invoke the Local Server
+
+To invoke an Agent running locally via the `<your-agent-name>-serve` target, you can send a simple POST request to `/invocations` on the port your local agent is running on. For example, with `curl`:
+
+```bash
+curl -N -X POST http://localhost:8081/invocations \
+  -d '{"message": "what is 3 + 5?"}' \
+  -H "Content-Type: application/json"
+```
+
+:::note[Curl Streaming Flag]
+The `-N` argument given to `curl` disables buffering the output stream, so you can see the streaming response in real-time.
+:::
+
+### Invoke the Deployed Agent
+
+<Snippet name="agent/runtime-arn" parentHeading="Invoke the Deployed Agent" />
+
+<Tabs syncKey="auth">
+<TabItem label="IAM" _filter={{ auth: 'IAM' }}>
+#### IAM Authentication
+
+For IAM Authentication, the request must be signed using AWS Signature Version 4 (SigV4).
+
+```bash
+acurl <region> bedrock-agentcore -N -X POST \
+'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
+-d '{"message": "what is 3 + 5?"}' \
+-H 'Content-Type: application/json'
+```
+
+<Drawer title="Sigv4 enabled curl" trigger="Click here for more details on configuring the above acurl command">
+<Snippet name="tools/acurl" />
+</Drawer>
+</TabItem>
+
+<TabItem label="Cognito" _filter={{ auth: 'Cognito' }}>
+#### JWT / Cognito Authentication
+
+For Cognito Authentication, pass the Cognito Access Token in the `Authorization` header:
+
+```bash
+curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
+  -d '{"message": "what is 3 + 5?"}' \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <access-token>"
+```
+
+You can obtain the access token using the AWS CLI's `cognito-idp admin-initiate-auth` command, for example:
+
+```bash
+aws cognito-idp admin-initiate-auth \
+  --user-pool-id <user-pool-id> \
+  --client-id <user-pool-client-id> \
+  --auth-flow ADMIN_NO_SRP_AUTH \
+  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
+  --region <region> \
+  --query 'AuthenticationResult.AccessToken' \
+  --output text
+```
+</TabItem>
+</Tabs>
+
+#### Browser / React Website
+
+For invoking your Agent from a React website, you can make use of the <Link path="/guides/connection/react-py-agent">`connection` generator</Link>, which automatically sets up a client with the correct authentication (IAM or Cognito).
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/react-py-agent">`connection` generator guide</Link> for details about how the connection is set up.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'A2A' }} description="A2A delegation details">
+### Invoking an A2A Agent as a Tool
+
+To delegate work from this agent to a remote A2A agent (either <Link path="/guides/ts-agent">TypeScript</Link> or <Link path="/guides/py-agent">Python</Link>), use the <Link path="/guides/connection/py-agent-a2a">`connection` generator</Link>. It vends a SigV4-authenticated client for the target agent and AST-transforms this agent's `agent.py` to register the remote A2A agent as a `@tool`-decorated delegate.
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/py-agent-a2a">`connection` generator guide</Link> for details about how the connection is set up.
+</OptionFilter>
+
+<OptionFilter when={{ protocol: 'AG-UI' }} description="AG-UI / React connection details">
+### Invoking an AG-UI Agent
+
+To invoke your AG-UI agent from a React website, use the <Link path="/guides/connection/react-agui">`connection` generator</Link>, which wires up a [CopilotKit](https://docs.copilotkit.ai/aws-strands) client configured for your deployed agent with the correct authentication (IAM or Cognito).
+
+<RunGenerator generator="connection" />
+
+Refer to the <Link path="/guides/connection/react-agui">`connection` generator guide</Link> for details about how the connection is set up.
+</OptionFilter>

package/docs/guides/py-mcp-server.mdx

@@ -0,0 +1,161 @@
+---
+title: Python MCP Server
+description: Generate a Python Model Context Protocol (MCP) server for providing context to Large Language Models
+generator: py#mcp-server
+---
+
+import { FileTree } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import NxCommands from '@components/nx-commands.astro';
+import Link from '@components/link.astro';
+import Snippet from '@components/snippet.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+Generate a Python [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for providing context to Large Language Models (LLMs), and optionally deploy it to [Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/).
+
+## What is MCP?
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI assistants to interact with external tools and resources. It provides a consistent way for LLMs to:
+
+- Execute tools (functions) that perform actions or retrieve information
+- Access resources that provide context or data
+
+## Usage
+
+### Generate an MCP Server
+
+You can generate a Python MCP server in two ways:
+
+<RunGenerator generator="py#mcp-server" />
+
+:::tip[Project Prerequisite]
+First use the <Link path="/guides/python-project">`py#project`</Link> generator to create a project to add your MCP server to.
+:::
+
+### Options
+
+<GeneratorParameters generator="py#mcp-server" />
+
+## Generator Output
+
+The generator will add the following files to your existing Python project:
+
+<FileTree>
+  - your-project/
+    - your_module/
+      - mcp_server/ (or custom name if specified)
+        - \_\_init\_\_.py Python package initialization
+        - server.py Main server definition with sample tools and resources
+        - stdio.py Entry point for STDIO transport, useful for simple local MCP servers
+        - http.py Entry point for Streamable HTTP transport, useful for hosting your MCP server
+        - Dockerfile Entry point for hosting your MCP server (excluded when `computeType` is set to `None`)
+    - pyproject.toml Updated with MCP dependencies
+    - project.json Updated with MCP server serve targets
+</FileTree>
+
+### Infrastructure
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment">
+<Snippet name="shared-constructs" />
+
+<Snippet name="mcp/shared-constructs" />
+</OptionFilter>
+
+<OptionFilter when={{ computeType: 'None' }} description="No infrastructure is vended for computeType=None">
+If you selected `None` for `computeType`, no CDK constructs or Terraform modules are generated — the MCP server is configured for local STDIO / HTTP use only. The `auth` option is ignored in this mode since there is no hosted endpoint to authenticate.
+</OptionFilter>
+
+#### Architecture
+
+<Snippet name="mcp/architecture" />
+
+## Working with Your MCP Server
+
+### Adding Tools
+
+Tools are functions that the AI assistant can call to perform actions. The Python MCP server uses the [MCP Python SDK (FastMCP)](https://github.com/modelcontextprotocol/python-sdk) library, which provides a simple decorator-based approach for defining tools.
+
+You can add new tools in the `server.py` file:
+
+```python
+@mcp.tool(description="Your tool description")
+def your_tool_name(param1: str, param2: int) -> str:
+    """Tool implementation with type hints"""
+    # Your tool logic here
+    return f"Result: {param1} with {param2}"
+```
+
+The FastMCP library automatically handles:
+- Type validation based on your function's type hints
+- JSON schema generation for the MCP protocol
+- Error handling and response formatting
+
+### Adding Resources
+
+Resources provide context to the AI assistant. You can add resources using the `@mcp.resource` decorator:
+
+```python
+@mcp.resource("example://static-resource", description="Static resource example")
+def static_resource() -> str:
+    """Return static content"""
+    return "This is static content that provides context to the AI"
+
+@mcp.resource("dynamic://resource/{item_id}", description="Dynamic resource example")
+def dynamic_resource(item_id: str) -> str:
+    """Return dynamic content based on parameters"""
+    # Fetch data based on item_id
+    data = fetch_data_for_item(item_id)
+    return f"Dynamic content for {item_id}: {data}"
+```
+
+## Configuring with AI Assistants
+
+<Snippet name="mcp/configuration-py" parentHeading="Configuring with AI Assistants" />
+
+## Running Your MCP Server
+
+### Inspector
+
+The generator configures a target named `<your-server-name>-inspect`, which starts the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) with the configuration to connect to your MCP server using STDIO transport.
+
+<NxCommands commands={['your-server-name-inspect your-project']} />
+
+This will start the inspector at `http://localhost:6274`. Get started by clicking on the "Connect" button.
+
+### STDIO
+
+The easiest way to test and use an MCP server is by using the inspector or configuring it with an AI assistant (as above).
+
+You can however run your server with [STDIO transport](https://modelcontextprotocol.io/docs/concepts/transports#standard-input%2Foutput-stdio) directly using the `<your-server-name>-serve-stdio` target.
+
+<NxCommands commands={['your-server-name-serve-stdio your-project']} />
+
+This command uses `uv run` to execute your MCP server with STDIO transport.
+
+### Streamable HTTP
+
+If you would like to run your MCP server locally using [Streamable HTTP transport](https://modelcontextprotocol.io/docs/concepts/transports#streamable-http), you can use the `<your-server-name>-serve` target.
+
+<NxCommands commands={['your-server-name-serve your-project']} />
+
+This command uses `uv run uvicorn --reload` to run your MCP server with HTTP transport (typically on port `8000`), and automatically restarts when files change.
+
+<OptionFilter when={{ computeType: 'BedrockAgentCoreRuntime' }} description="Bedrock AgentCore Runtime deployment details">
+## Deploying Your MCP Server to Bedrock AgentCore Runtime
+
+<Snippet name="mcp/bedrock-deployment" parentHeading="Deploying Your MCP Server to Bedrock AgentCore Runtime" />
+
+### Bundle and Docker Targets
+
+In order to build your MCP server for Bedrock AgentCore Runtime, a `bundle` target is added to your project, which:
+
+- Exports your Python dependencies to a `requirements.txt` file using `uv export`
+- Installs dependencies for the target platform (`aarch64-manylinux_2_28`) using `uv pip install`
+
+A `docker` target specific to your MCP server is also added, which copies the `Dockerfile` and bundled artifacts into a docker context directory. This co-locates the `Dockerfile` with the built output, allowing CDK to build the Docker image directly using `AgentRuntimeArtifact.fromAsset`.
+
+### Observability
+
+<Snippet name="mcp/observability" parentHeading="Observability" />
+</OptionFilter>