# Partner Central agents MCP Server
The Partner Central agents MCP Server provides Partner Central tools through the Model Context Protocol (MCP), enabling your AI agents and tools to discover and interact with opportunity management, customer insights, and funding programs through natural language.
The server handles authentication, session management, and human-in-the-loop approval for write operations maintaining control while streamlining workflows.
## Overview
The Partner Central agents MCP Server is a fully managed, AWS-hosted service that connects MCP-compatible AI clients to the Partner Central agents. It uses JSON-RPC 2.0 over HTTPS with SigV4 authentication and supports Server-Sent Events (SSE) for real-time streaming responses.
The server supports multi-turn conversations, file attachments for document analysis, and a built-in approval workflow that requires your explicit consent before any write operation executes.
### Agent capabilities
+ **Pipeline insights** — Get conversational intelligence about your sales pipeline, including at-risk opportunities, stage progression, and closed-lost analysis
+ **Opportunity summary** — Generate concise, at-a-glance summaries of any deal covering stage, spend, close date, and more
+ **Sales play generation** — Build customized sales strategies combining opportunity details, industry context, and AWS solution recommendations
+ **Customer profile creation** — Generate company profiles using publicly available information covering industry, business model, geography, and recent developments
+ **Solution recommendation** — Cross-reference your registered solutions against opportunity requirements to find the best match
+ **Funding recommendation** — Evaluate opportunities against available AWS funding programs, estimate amounts, and create fund requests
+ **Next step recommendations** — Get prioritized action plans grounded in AWS co-sell standards and stage progression guidance
+ **Opportunity progression** — Upload supporting documents, extract relevant data, and progress opportunities through pipeline stages
## Key benefits
+ **Conversational access to Partner Central** — Ask questions in natural language instead of navigating complex console workflows
+ **Human-in-the-loop safety** — All write operations require your explicit approval before execution
+ **Multi-turn conversations** — Refine your queries within a session without repeating context
+ **File analysis** — Attach documents (PDF, DOCX, XLSX, CSV, images) for the agent to analyze alongside your questions
+ **Centralized access management** — Control access through IAM policies with fine-grained permissions
+ **Sandbox testing** — Test workflows in an isolated sandbox environment before touching production data
+ **Streaming responses** — Get feedback via SSE as the agent processes your request
## Usage examples
All AI-generated insights include a Session ID for traceability. Data is isolated to the logged-in partner's own opportunities. All content carries clear disclosure labels and is governed by the [AWS Responsible AI Policy](https://aws.amazon.com/machine-learning/responsible-ai/policy/).
### Pipeline insights
Get conversational intelligence about your sales pipeline. The agent analyzes stage progression, deadlines, stalled deals, and closed-lost patterns to surface what matters most.
+ "Which opportunities need my attention this week?"
+ "How many opportunities are closing next month?"
+ "What are the top reasons we've lost opportunities in the last 6 months?"
### Opportunity summary
The agent synthesizes company name, industry, stage, expected monthly AWS spend, target close date, and other key details into a concise summary — no need to scan individual form fields.
+ "Give me a summary of opportunity O1234567890"
+ "What's the current status and key details for the Acme Corp deal?"
### Sales play generation
The agent builds a customized sales strategy by combining the opportunity's details, the customer's industry context, and relevant AWS solution recommendations into a ready-to-use sales play.
+ "Generate a sales play for opportunity O1234567890"
+ "What's the best approach to sell cloud migration to this financial services customer?"
+ "Build me a sales strategy for the GlobalTech data analytics deal"
### Customer profile creation
The agent generates a company profile using publicly available information — covering industry classification, business model (B2B/B2C/hybrid), geographic presence, company size, market focus, and recent business developments. Profiles are labeled "Generated with publicly available data and AWS AI insights."
+ "Create a customer profile for Acme Corp"
+ "What do we know about this customer's industry and business model?"
+ "Pull together a company overview for my upcoming meeting with GlobalTech"
### Solution recommendation
The agent cross-references your registered solutions against opportunity requirements, showing solution name, description, and whether it's already attached to the opportunity.
+ "Which of our solutions best match opportunity O1234567890?"
+ "Is our data analytics solution already attached to this deal?"
+ "Recommend solutions for a customer looking to migrate their SAP workloads"
### Funding recommendation
The agent evaluates each opportunity against available AWS funding programs based on opportunity details and program eligibility criteria. When a match is found, it displays program name, description, and detailed reasoning. You can then estimate funding amounts, create auto-populated fund request drafts, or learn more about programs conversationally. SCA (Strategic Collaboration Agreement) budget availability is surfaced when relevant, and all actions respect IAM permissions.
+ "Am I eligible for any funding programs on opportunity O6789012345?"
+ "Estimate the funding amount for a POC with this customer"
+ "Create a MAP benefit application for this opportunity"
### Next step recommendations
The agent evaluates the opportunity against AWS's stage progression guidance, compares current data against criteria for well-qualified opportunities, and identifies exactly what information you still need to collect. The result is a prioritized action plan grounded in AWS co-sell standards.
+ "What do I need to do next to advance opportunity O1234567890?"
+ "Is this opportunity ready for submission? What fields are missing?"
+ "What are the requirements to move this deal from Prospect to Qualified?"
### Opportunity progression
The agent accepts supporting documents (meeting transcripts, call notes, email summaries), extracts relevant information, maps it to opportunity fields, evaluates stage requirements, and updates the opportunity. If gaps remain, it returns a breakdown of satisfied vs. unsatisfied requirements.
+ "Here are my call notes — update opportunity O1234567890 with the relevant details"
+ "I'm attaching the meeting transcript. Progress this opportunity based on what we discussed."
+ "Review this email summary and tell me which opportunity fields it satisfies"
## Get started
Ready to set up the Partner Central agents MCP Server? Head to the [Getting started](https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-getting-started.html) guide for step-by-step setup instructions.
# Getting Started with the Partner Central Agent MCP Server
This guide walks you through setting up programmatic access to the Partner Central Agent MCP Server using a custom MCP client. The server uses direct HTTPS with SigV4 authentication — no proxy or IDE plugin required.
## Prerequisites
Before you begin, make sure you have:
+ An active Partner Central account (migrated to the AWS console)
+ An AWS account with IAM permissions for Partner Central
+ AWS CLI installed and configured with credentials
+ Access to the us-east-1 (N. Virginia) region
+ HTTPS connectivity to `partnercentral-agents-mcp.us-east-1.api.aws`
+ TLS 1.2\$1 support in your HTTP client
+ An MCP-compatible client that supports JSON-RPC 2.0 and SigV4 request signing
## Step 1: Set up IAM permissions
The Partner Central Agent MCP Server requires IAM permissions at two levels: protocol access (to communicate with the MCP endpoint) and data access (to perform Partner Central operations).
### Attaching IAM policies
To attach a policy to your IAM identity using the AWS Management Console:
1. Open the [IAM console](https://console.aws.amazon.com/iam/).
1. In the left navigation pane, choose **Users**, **User groups**, or **Roles** depending on the identity you want to attach the policy to, then choose the name of the specific user, group, or role.
1. Choose the **Permissions** tab.
1. Choose **Attach policies** (or **Add permissions** if it's the first time).
1. In the policy list, search for and select the managed policy you want to attach (for example, a custom policy you created from the JSON blocks below).
1. Choose **Attach policies** (or **Next** and then **Add permissions**) to confirm.
The permissions take effect immediately. You can attach multiple policies to the same identity.
### Recommended: Use the managed policy
The simplest way to grant MCP protocol access is to attach the `AWSMcpServiceActionsFullAccess` managed policy to your IAM identity. This policy includes all permissions needed to interact with the MCP server.
For fine-grained control, you can use the `aws:IsMcpServiceAction` condition key in your IAM policies to scope permissions specifically to MCP service actions.
### Minimum permissions for MCP protocol access
At minimum, your IAM identity needs this action to interact with the MCP server:
| Action | Description |
| --- | --- |
| partnercentral:UseSession | Required to create, update, and retrieve conversation sessions |
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"partnercentral:UseSession"
],
"Resource": "*",
"Condition": {
"Bool": {
"aws:IsMcpServiceAction": "true"
}
}
}
]
}
```
### Data access permissions
To actually perform Partner Central operations through the agent, you need additional permissions based on your use case.
**Opportunity management:**
```
{
"Effect": "Allow",
"Action": [
"partnercentral:List*",
"partnercentral:Get*",
"partnercentral:UpdateOpportunity",
"partnercentral:SubmitOpportunity",
"partnercentral:AssignOpportunity",
"partnercentral:AssociateOpportunity",
"partnercentral:DisassociateOpportunity"
],
"Resource": "*"
}
```
**Funding programs:**
```
{
"Effect": "Allow",
"Action": [
"partnercentral:ListBenefitAllocations",
"partnercentral:ListBenefitApplications",
"partnercentral:CreateBenefitApplication",
"partnercentral:GetBenefitApplication",
"partnercentral:UpdateBenefitApplication",
"partnercentral:SubmitBenefitApplication",
"partnercentral:AmendBenefitApplication",
"partnercentral:CancelBenefitApplication",
"partnercentral:RecallBenefitApplication",
"partnercentral:AssociateBenefitApplicationResource",
"partnercentral:DisassociateBenefitApplicationResource"
],
"Resource": "*"
}
```
**Marketplace access:**
```
{
"Effect": "Allow",
"Action": [
"aws-marketplace:DescribeEntity",
"aws-marketplace:DescribeAgreement",
"aws-marketplace:SearchAgreements",
"aws-marketplace:ListEntities"
],
"Resource": "*"
}
```
### Full access policy
For development and testing, you can combine all permissions into a single policy:
```
aws iam create-policy \
--policy-name PartnerCentralAgentsFullAccess \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"partnercentral:UseSession",
"partnercentral:List*",
"partnercentral:Get*",
"partnercentral:UpdateOpportunity",
"partnercentral:SubmitOpportunity",
"partnercentral:AssignOpportunity",
"partnercentral:AssociateOpportunity",
"partnercentral:DisassociateOpportunity",
"partnercentral:CreateResourceSnapshot",
"partnercentral:CreateResourceSnapshotJob",
"partnercentral:StartResourceSnapshotJob",
"partnercentral:CreateEngagement",
"partnercentral:CreateEngagementInvitation",
"partnercentral:RejectEngagementInvitation",
"partnercentral:StartEngagementByAcceptingInvitationTask",
"partnercentral:StartEngagementFromOpportunityTask",
"partnercentral:CreateBenefitApplication",
"partnercentral:UpdateBenefitApplication",
"partnercentral:SubmitBenefitApplication",
"partnercentral:AmendBenefitApplication",
"partnercentral:CancelBenefitApplication",
"partnercentral:RecallBenefitApplication",
"partnercentral:AssociateBenefitApplicationResource",
"partnercentral:DisassociateBenefitApplicationResource"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"aws-marketplace:DescribeEntity",
"aws-marketplace:DescribeAgreement",
"aws-marketplace:SearchAgreements",
"aws-marketplace:ListEntities"
],
"Resource": "*"
}
]
}'
```
### Read-only policy
For production environments or read-only use cases, restrict permissions to read operations:
```
aws iam create-policy \
--policy-name PartnerCentralAgentReadOnly \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"partnercentral:UseSession",
"partnercentral:List*",
"partnercentral:Get*"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"aws-marketplace:DescribeEntity",
"aws-marketplace:DescribeAgreement",
"aws-marketplace:SearchAgreements",
"aws-marketplace:ListEntities"
],
"Resource": "*"
}
]
}'
```
## Step 2: Connect your MCP client
The Partner Central Agent MCP Server uses direct HTTPS with SigV4 request signing. There is no proxy layer — your MCP client sends JSON-RPC 2.0 requests directly to the endpoint.
### Endpoint
```
https://partnercentral-agents-mcp.us-east-1.api.aws/mcp
```
### Authentication
All requests must be signed with [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) using:
+ Service name: `partnercentral-agents-mcp`
+ Region: `us-east-1`
### Initialize the MCP connection
Send an `initialize` request to establish the protocol:
```
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": {
"name": "my-partner-client",
"version": "1.0.0"
}
}
}
```
Expected response:
```
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2025-03-26",
"capabilities": {
"tools": {
"listChanged": false
}
},
"serverInfo": {
"name": "PartnerCentralAgentMCPServer",
"version": "1.0.0"
}
}
}
```
### List available tools
```
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
```
## Signing your calls with MCP header
When making requests to Partner Central agents MCP, we recommend including the custom MCP header using the following methods to help AWS identify the source of the client application, monitor usage, and audit performance. AWS uses this header to distinguish the type of client application making the call and to gather insights about the success rate of different client implementations.
### Method 1: \$1meta field (programmatic/stateless MCP)
For code that directly constructs MCP `tools/call` requests, provide the `_meta` field on requests.
```
{
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"content": [
{
"type": "text",
"text": "List my open opportunities with expected close date in Q1 2026"
}
],
"catalog": "AWS"
},
"_meta": {
"integrator": "",
"sourceProduct": ""
}
}
}
```
### Method 2: clientInfo (session-based custom agents)
For custom MCP clients establishing sessions, provide MCP header info inside the `clientInfo` field:
```
{
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"clientInfo": {
"integrator": "",
"sourceProduct": ""
}
}
}
```
Fields in `clientInfo`:
+ `integrator` — Company name or "Direct" for partners
Example: `AWS`
+ `sourceProduct` — Product/agent name
Example: `AWS CRM Connector`
### Method 3: URL parameter (hosted MCP only)
Only for hosted MCP clients where the integrator cannot modify protocol fields. Use the URL parameter:
Server URL: `https://mcp.partnercentral.aws?appId=`
## Step 3: Verify your setup
Send a simple message to confirm everything is working. Use the `Sandbox` catalog for testing:
```
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"content": [
{
"type": "text",
"text": "Hello, what can you help me with?"
}
],
"catalog": "Sandbox"
}
}
}
```
If you receive a response with `"status": "complete"` and a text reply from the agent, your setup is working correctly. The response will also include a `sessionId` that you can use for follow-up messages.
## Step 4: Run your first tasks
### Query your opportunities
```
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"content": [
{
"type": "text",
"text": "List my open opportunities with expected revenue over $50K"
}
],
"catalog": "AWS"
}
}
}
```
### Check funding eligibility
```
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"content": [
{
"type": "text",
"text": "Am I eligible for MAP funding for opportunity O1234567890?"
}
],
"catalog": "AWS"
}
}
}
```
### Retrieve session history
```
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "getSession",
"arguments": {
"sessionId": "session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"catalog": "AWS"
}
}
}
```
## Security considerations
+ Do not pass AWS credentials through MCP tool parameters. Authentication is handled by SigV4 request signing at the transport layer.
+ Use the Sandbox catalog for testing and development. The `"Sandbox"` catalog provides an isolated environment that does not affect production partner data.
+ Apply least-privilege IAM policies in production. Use the read-only policy for monitoring and reporting use cases. Only grant write permissions when the user needs to update opportunities or submit funding applications.
+ Review write operations carefully. The server uses human-in-the-loop approval for all write operations. When a write action is proposed, review the parameters before approving.
+ Session data is transient. Sessions expire 48 hours after creation. Do not rely on sessions for long-term data storage.
+ File uploads go to an ephemeral S3 bucket. Uploaded files are stored temporarily and are not retained permanently. Do not upload files containing credentials, secrets, or other sensitive information.
## Next steps
+ [https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-configuration-reference.html](https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-configuration-reference.html) — Full reference for endpoint, IAM actions, session management, and error codes
+ [https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-tools-reference.html](https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-tools-reference.html) — Detailed documentation for `sendMessage` and `getSession` tools
# Configuration Reference
This page provides the complete reference for connecting to and configuring the Partner Central Agent MCP Server.
## Endpoint
| Property | Value |
| --- | --- |
| URL | https://partnercentral-agents-mcp.us-east-1.api.aws/mcp |
| Region | us-east-1 (N. Virginia) only |
| Protocol | JSON-RPC 2.0 over HTTPS |
| Streaming | Server-Sent Events (SSE) |
| Authentication | AWS Signature Version 4 |
| SigV4 service name | partnercentral-agents-mcp |
| TLS requirement | TLS 1.2 or higher |
## IAM permissions
All IAM actions use the `partnercentral:` prefix unless otherwise noted.
### MCP protocol access
The simplest way to grant MCP protocol access is to attach the `AWSMcpServiceActionsFullAccess` managed policy to your IAM identity. This policy includes all permissions needed to interact with the MCP server. For fine-grained control, you can use the `aws:IsMcpServiceAction` condition key in your IAM policies to scope permissions specifically to MCP service actions.
| Action | Description |
| --- | --- |
| partnercentral:UseSession | Create, update, and retrieve conversation sessions |
### Opportunity management
| Action | Description |
| --- | --- |
| partnercentral:List\$1 | List opportunities, solutions, and other Partner Central resources |
| partnercentral:Get\$1 | Retrieve details for individual opportunities and other resources |
| partnercentral:UpdateOpportunity | Modify opportunity fields (stage, close date, revenue, etc.) |
| partnercentral:SubmitOpportunity | Submit an opportunity for AWS review |
| partnercentral:AssignOpportunity | Assign an opportunity to a partner representative |
| partnercentral:AssociateOpportunity | Link an opportunity to another resource (solution, etc.) |
| partnercentral:DisassociateOpportunity | Remove a link between an opportunity and another resource |
| partnercentral:StartEngagementFromOpportunityTask | Submit opportunities to start an engagement from an opportunity |
### Funding programs
| Action | Description |
| --- | --- |
| partnercentral:ListBenefitAllocations | List available benefit allocations for your account |
| partnercentral:ListBenefitApplications | List submitted benefit applications |
| partnercentral:CreateBenefitApplication | Create a new benefit application (MAP, POC, WMP) |
| partnercentral:GetBenefitApplication | Retrieve details of a specific benefit application |
| partnercentral:UpdateBenefitApplication | Update a pending benefit application |
| partnercentral:AssociateBenefitApplicationResource | Link a resource to a benefit application |
| partnercentral:DisassociateBenefitApplicationResource | Remove a resource link from a benefit application |
### Marketplace access
| Action | Description |
| --- | --- |
| aws-marketplace:DescribeEntity | Retrieve details of a marketplace entity |
| aws-marketplace:SearchAgreements | Search marketplace agreements |
| aws-marketplace:ListEntities | List marketplace entities |
## Catalog environments
| Catalog | Description |
| --- | --- |
| "AWS" | Production environment. All operations affect live partner data. |
| "Sandbox" | Isolated testing environment. No impact on production data. Use for development and validation. |
## Session management
| Property | Value |
| --- | --- |
| Session ID format | UUID v4 with session- prefix (e.g., session-550e8400-e29b-41d4-a716-446655440000) |
| Session creation | Automatic on first sendMessage call without a sessionId |
| Session expiry | 48 hours from session creation (absolute expiry, not inactivity-based) |
## File upload
| Property | Value |
| --- | --- |
| Max files per message | 3 |
| Image size limit | 3.75 MB |
| Document size limit | 4.5 MB |
| Allowed extensions | doc, docx, pdf, png, jpeg, xlsx, csv, txt |
| S3 bucket (production) | aws-partner-central-marketplace-ephemeral-writeonly-files |
| Upload path | s3://\$1bucket\$1/\$1aws-account-id\$1/ |
| S3 URI requirement | Must include versionId query parameter |
### Upload workflow
1. Upload your file to the appropriate S3 bucket under your AWS account ID prefix.
1. Note the S3 URI including the `versionId` returned by the upload.
1. Include the file as a `document` content block in your `sendMessage` call.
Example S3 URI format:
```
s3://aws-partner-central-marketplace-ephemeral-writeonly-files/123456789012/my-document.pdf?versionId=abc123
```
## Error codes
| Code | Name | Description |
| --- | --- | --- |
| -32001 | AUTHENTICATION\$1FAILURE | SigV4 signature is invalid or credentials have expired |
| -31004 | TOOL\$1PERMISSION\$1DENIED | IAM identity lacks the required partnercentral: action for this operation |
| -32002 | ACCESS\$1DENIED | General access denied (account not enrolled, region mismatch, etc.) |
| -32004 | LIMIT\$1EXCEEDED | Rate limit or quota exceeded. Retry with exponential backoff. |
| -30001 | RESOURCE\$1NOT\$1FOUND | Requested resource (session, opportunity, etc.) does not exist |
| -32600 | INVALID\$1REQUEST | Malformed JSON-RPC request or invalid parameters |
| -32603 | INTERNAL\$1ERROR | Server-side error. Retry the request. |
## Rate limits
The server enforces per-account rate limits:
| Operation | Sustained rate | Burst |
| --- | --- | --- |
| sendMessage | 2 requests per minute | 10 |
| All other operations | 10 requests per minute | 20 |
If you exceed these limits, the server returns error code `-32004` (LIMIT\$1EXCEEDED). Implement exponential backoff with jitter in your client to handle rate limiting gracefully.
## Streaming (SSE) event types
When `stream` is set to `true` in a `sendMessage` call, the server returns Server-Sent Events with these event types:
| Event Type | Description |
| --- | --- |
| stream\$1start | Stream connection established |
| assistant-response.start | Agent has begun generating a response |
| assistant-response.delta | Incremental text chunk of the agent's response |
| assistant-response.completed | Agent has finished generating the response |
| server-tool-use | Agent is invoking an internal tool (read operation) |
| server-tool-response | Result of an internal tool invocation |
| tool\$1approval\$1request | Agent is requesting human approval for a write operation |
| stream\$1end | Stream connection closing |
| done | Final event indicating the SSE stream is complete |
## Next steps
+ [https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-tools-reference.html](https://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-tools-reference.html) — Detailed documentation for `sendMessage` and `getSession` tools
# Tools Reference
The Partner Central Agent MCP Server exposes two MCP tools: `sendMessage` for all agent interactions, and `getSession` for retrieving session state. All Partner Central operations — opportunity queries, funding applications, document analysis — are handled through natural language via `sendMessage`.
## Tools overview
| Tool | Description | Category |
| --- | --- | --- |
| sendMessage | Send messages to the Partner Central AI agent. Supports text, file attachments, and human-in-the-loop approval responses. | Read / Write |
| getSession | Retrieve session state including conversation history, events, and metadata. | Read-only |
## `sendMessage`
Primary tool for all Partner Central AI agent interactions. Use this tool to ask questions, request actions, attach documents for analysis, and respond to approval requests for write operations.
The agent maintains conversation context within a session, so you can ask follow-up questions without repeating prior context.
### Parameters
+ `content` (required) — Array of content blocks. Each block must include a `type` field that determines the block structure. You can include multiple blocks in a single message (e.g., text \$1 document attachment).
Content block types:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/partner-central/latest/APIReference/mcp-tools-reference.html)
+ `catalog` (required) — Target environment for the operation.
Valid values: `"AWS"` (production), `"Sandbox"` (testing)
+ `sessionId` (optional) — UUID v4 identifying an existing session to continue. Omit to create a new session. Format: `session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
Default: A new session is created automatically.
+ `stream` (optional) — Enable Server-Sent Events (SSE) streaming for real-time response delivery.
Valid values: `true`, `false`
Default: `false`
### Response
The response includes:
| Field | Description |
| --- | --- |
| sessionId | Session identifier for follow-up messages |
| status | Response status: "complete", "requires\$1approval", or "error" |
| content | Array of response content blocks from the agent |
### Examples
#### Basic text message (new session)
Request:
```
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"content": [
{
"type": "text",
"text": "List my open opportunities with expected close date in Q1 2026"
}
],
"catalog": "AWS"
}
}
}
```
Response:
```
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "I found 12 open opportunities with expected close dates in Q1 2026. Here's a summary:\n\n1. **O1234567890** - Acme Corp Cloud Migration - $250,000 - Qualified stage\n2. **O1234567891** - GlobalTech Data Analytics - $180,000 - Prospect stage\n..."
}
],
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"status": "complete"
}
}
```
#### Follow-up message (existing session)
Request:
```
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"content": [
{
"type": "text",
"text": "Tell me more about O1234567890. Is it ready for submission?"
}
],
"catalog": "AWS"
}
}
}
```
#### File attachment
Upload a document to S3 first, then reference it in the message:
```
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"content": [
{
"type": "text",
"text": "Review this customer proposal and suggest which opportunity it aligns with"
},
{
"type": "document",
"filename": "acme-proposal.pdf",
"s3Uri": "s3://aws-partner-central-marketplace-ephemeral-writeonly-files/123456789012/acme-proposal.pdf?versionId=abc123def456"
}
],
"catalog": "AWS"
}
}
}
```
File upload constraints:
+ Maximum 3 files per message
+ Image size limit: 3.75 MB
+ Document size limit: 4.5 MB
+ Allowed extensions: `doc`, `docx`, `pdf`, `png`, `jpeg`, `xlsx`, `csv`, `txt`
+ Files must be uploaded to `s3://{bucket}/{your-aws-account-id}/`
+ The S3 URI must include the `versionId` query parameter
### Human-in-the-loop approval workflow
When the agent needs to perform a write operation (e.g., update an opportunity, submit a funding application), it returns a `"requires_approval"` status with the proposed action details. You must respond with a `tool_approval_response` content block.
**Step 1 — Agent requests approval:**
```
{
"jsonrpc": "2.0",
"id": 4,
"result": {
"content": [
{
"type": "text",
"text": "I'd like to update opportunity O1234567890 with the following changes:\n- Target close date: 2026-03-31\n- Expected revenue: $300,000\n- Stage: Qualified\n\nPlease approve, reject, or override this action."
},
{
"type": "tool_approval_request",
"toolUseId": "tool-use-98765",
"toolName": "update_opportunity_enhanced",
"parameters": {
"opportunityId": "O1234567890",
"targetCloseDate": "2026-03-31",
"expectedRevenue": 300000,
"stage": "Qualified"
}
}
],
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"status": "requires_approval"
}
}
```
**Step 2 — Approve the action:**
```
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"content": [
{
"type": "tool_approval_response",
"toolUseId": "tool-use-98765",
"decision": "approve"
}
],
"catalog": "AWS"
}
}
}
```
**Step 2 (alternative) — Reject the action:**
```
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"content": [
{
"type": "tool_approval_response",
"toolUseId": "tool-use-98765",
"decision": "reject",
"message": "The expected revenue should be $250,000, not $300,000"
}
],
"catalog": "AWS"
}
}
}
```
**Step 2 (alternative) — Override with custom response:**
```
{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"content": [
{
"type": "tool_approval_response",
"toolUseId": "tool-use-98765",
"decision": "override",
"message": "Use expected revenue of $250,000 and keep the stage as Prospect instead"
}
],
"catalog": "AWS"
}
}
}
```
Approval decision values:
| Decision | Behavior |
| --- | --- |
| "approve" | Execute the tool with the proposed parameters |
| "reject" | Do not execute the tool. Optional message explains why. |
| "override" | Provide a custom response or modified instructions via message |
### Streaming with SSE
Enable streaming to receive incremental response chunks as the agent processes your request:
Request:
```
{
"jsonrpc": "2.0",
"id": 6,
"method": "tools/call",
"params": {
"name": "sendMessage",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"content": [
{
"type": "text",
"text": "Analyze my pipeline and identify opportunities at risk"
}
],
"catalog": "AWS",
"stream": true
}
}
}
```
The server responds with a stream of SSE events:
```
event: stream_start
data: {"sessionId": "session-550e8400-e29b-41d4-a716-446655440000"}
event: assistant-response.start
data: {}
event: server-tool-use
data: {"toolName": "analyze_pipeline", "parameters": {}}
event: server-tool-response
data: {"toolName": "analyze_pipeline", "result": {"opportunitiesAnalyzed": 47, "atRisk": 5}}
event: assistant-response.delta
data: {"text": "I analyzed your pipeline of 47 opportunities and identified "}
event: assistant-response.delta
data: {"text": "5 that are at risk of slipping:\n\n"}
event: assistant-response.delta
data: {"text": "1. **O2345678901** - Close date is past due by 15 days\n"}
event: assistant-response.completed
data: {"status": "complete"}
event: stream_end
data: {}
```
## `getSession`
Retrieve the current state of a conversation session, including full conversation history, events, and metadata. Use this to inspect session state, review past interactions, or resume a conversation.
### Parameters
+ `sessionId` (required) — UUID of the session to retrieve. Format: `session-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`.
+ `catalog` (required) — Environment the session belongs to.
Valid values: `"AWS"`, `"Sandbox"`
### Response
| Field | Type | Description |
| --- | --- | --- |
| sessionId | string | Session identifier |
| createdAt | string | ISO 8601 timestamp of session creation |
| lastActivity | string | ISO 8601 timestamp of last activity |
| sequenceNumber | integer | Current event sequence number |
| stateType | string | Current session state |
| events | array | Full conversation history (user messages, agent responses, tool uses) |
| variables | object | Session variables and metadata |
| eventCount | integer | Total number of events in the session |
### Example
Request:
```
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "getSession",
"arguments": {
"sessionId": "session-550e8400-e29b-41d4-a716-446655440000",
"catalog": "AWS"
}
}
}
```
Response:
```
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"content": [
{
"type": "text",
"text": "{\"sessionId\":\"session-550e8400-e29b-41d4-a716-446655440000\",\"createdAt\":\"2026-01-15T10:30:00Z\",\"lastActivity\":\"2026-01-15T11:45:00Z\",\"sequenceNumber\":8,\"stateType\":\"END_TURN\",\"eventCount\":8,\"events\":[...],\"variables\":{}}"
}
]
}
}
```
## Error handling
All errors follow the JSON-RPC 2.0 error format:
```
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32001,
"message": "Authentication failed. Verify your SigV4 credentials and ensure they have not expired."
}
}
```
See [Error codes](mcp-configuration-reference.md#mcp-config-error-codes) for the complete list of error codes and their meanings.
**Recommended retry strategy**
+ For `-32004` (LIMIT\$1EXCEEDED): Retry with exponential backoff starting at 1 second
+ For `-32603` (INTERNAL\$1ERROR): Retry up to 3 times with exponential backoff
+ For `-32001` (AUTHENTICATION\$1FAILURE): Refresh credentials and retry
+ For all other errors: Do not retry automatically — inspect the error message and correct the request