Backend MCP instructions are replaced by the proxy's own
- Dominant language
- Python
- Stars
- 352
- Forks
- 63
- Avg merge
- 12h 9m
- Merged PRs (30d)
- 19
Description
### What happens
The proxy returns its own `instructions` on `initialize`, discarding whatever the backend sent. A client is told about the transport instead of about the tools.
Measured against a Bedrock AgentCore Gateway on v1.6.6:
| | `serverInfo` | `instructions` |
| --- | --- | --- |
| Backend, called directly with SigV4 | `mtp-mercell-mcp` | `Tools over ... development and operational data. All tools are read-only ... Call skills_get first for guidance ...` |
| Through `mcp-proxy-for-aws` | `MCP Proxy for AWS` | `MCP Proxy for AWS provides access to SigV4 protected MCP servers through a single interface. ...` |
### Why it matters
`instructions` is the one channel a backend has to tell a client what it is for, and it is delivered only on `initialize`. Our gateway uses it to point clients at a tool that loads platform guidance. That pointer never arrives, so the guidance is never loaded — and there is no way to tell from the client side that anything was dropped.
Tool names, descriptions and schemas all come through unchanged, so those remain a usable channel. `instructions` is the only one that does not.
### Where it comes from
`InitializeMiddleware._overwrite_init_options` already reads the backend's `InitializeResult` and copies one field out of it:
```python
fastmcp_ctx._session._init_options.capabilities = init_result.capabilities
```
Its docstring says the response will contain "the backend server's info instead of the proxy's defaults", but only `capabilities` is copied. `instructions` is a field on `InitializationOptions` already, so the seam exists.
### Suggested behaviour
Opt-in, so nothing changes for clients relying on the current text:
- `--proxy-instructions`, or `AWS_MCP_PROXY_INSTRUCTIONS=1`
- applied only when the backend actually sends instructions, so a backend without any keeps the proxy description rather than an empty field
- `serverInfo` left alone — there genuinely is a proxy in the path
Happy to open a PR; I have this working and tested locally.
### Environment
`mcp-proxy-for-aws` 1.6.6, Python 3.12, backend is a Bedrock AgentCore Gateway (`--service bedrock-agentcore`).
Contributor guide
Research direction
Start at InitializeMiddleware._overwrite_init_options and its docstring, then inspect how initialization options and proxy configuration are handled. Add coverage for the opt-in behavior where backend instructions are preserved only when supplied, and verify that the proxy fallback remains unchanged when they are absent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, python
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 76/100