Forward region via meta

[kyoncal]

Extension of #62

Summary

Implemented automatic AWS_REGION metadata injection into MCP JSON-RPC requests using httpx request hooks. Added _inject_metadata_hook function to hooks.py that injects metadata into the _meta field of request params, merging with existing metadata when present (existing values take precedence). Added optional metadata argument. Includes unit tests and an end-to-end integration test with a new echo_metadata tool in the test MCP server to verify metadata transmission.

User experience

AWS_REGION is now automatically injected into all MCP requests transparently - no manual configuration required. The proxy adds region information to the _meta field, making it available to MCP servers without any client-side code changes.

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Is this a breaking change? (Y/N)

• Yes
• No

Please add details about how this change was tested.

• Did integration tests succeed?
• If the feature is a new use case, is it necessary to add a new integration test case?

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[wzxxing]

per the mcp spec, the _meta field is https://modelcontextprotocol.io/specification/2025-06-18/basic/index#meta

Should we communicate with the teams owning remote MCP that we will use their endpoint as the key in meta? The resulted meta field would look like:

{
    "params": {
        "_meta": {
            "some-mcp-server.us-east-1.amazonaws.com/config": {
                "key": "value",
                "from": "cli-args"
            }
        }
    }
}

[kyoncal]

Using their endpoint as a key could be an idea for the future, however, I don't see it adding much value right, especially since there is currently only one metadata field that we set.

[wzxxing]

Optionally, our cli program can take an argument --config-key as the key in _meta.

[wzxxing]

Yes, the prefix is optional. But then the config key needs to be chosen carefully.

[kyoncal]

To my knowledge, the only thing that matters with regard to naming is that these rules are followed and that the user doesn't break them:

Prefix:

If specified, MUST be a series of labels separated by dots (.), followed by a slash (/).
    Labels MUST start with a letter and end with a letter or digit; interior characters can be letters, digits, or hyphens (-).
Any prefix beginning with zero or more valid labels, followed by modelcontextprotocol or mcp, followed by any valid label, is reserved for MCP use.
    For example: modelcontextprotocol.io/, mcp.dev/, api.modelcontextprotocol.org/, and tools.mcp.com/ are all reserved.

Name:

Unless empty, MUST begin and end with an alphanumeric character ([a-z0-9A-Z]).
MAY contain hyphens (-), underscores (_), dots (.), and alphanumerics in between.

Perhaps we can add some sort of sanitation? Changing the spec that other people expect at this point might not be optimal

[JacquesPotgieter]

Is there a reason why we are always setting this metadata?

I'm just wondering if we shouldn't set nothing in the default case, and users must specify the param if they want to use this

[kyoncal]

From my understanding of the intended workflow, there is no variation wherein an AWS_REGION is not necessary. If this is not the case, I'm happy to make it entirely optional.

[JacquesPotgieter]

Let's maybe differentiate between "feature-request" and "how other projects will use it". The "feature-request" here is to add the ability to add metadata.

With that in mind, I think let's make it completely optional

[arangatang]

I did like the hooks seperation, maybe we can reshuffle again later without the circular dep. For now this looks ok. Thanks for the work @kyoncal!