Configure GW-to-GW authentication and routing

By the end of this guide, you will have validated source and target authentication flows across a live GW-to-GW MCP connection, with log evidence confirming behavior at each hop.

This guide assumes two gateways are already connected and MCP surfaces exist on both. It walks through eight authentication scenarios covering source auth enforcement, target auth secret injection, and combined cross-gateway flows. For the connection setup this guide requires, see Connect two gateways.

Without running these scenarios before production, mismatched header names or incorrect secrets between gateways are only visible in live failures. Each scenario isolates one failure mode so problems can be caught in a controlled environment.

Use this guide when:

• You have connected two gateways and need to confirm auth behavior end-to-end.
• You are building a cross-organisation MCP workflow and need a validation checklist before deployment.

What you are building

• Company A hosts Agent GW 1 with MCP surface A.
• Company B hosts Agent GW 2 with MCP surface B.
• Gateways are connected through a DIDComm gateway connection.
• Agent GW 2 routes requests to Agent GW 1.
• Agent GW 1 forwards to an MCP backend service.

This pattern supports automated AI-driven workflows across company boundaries while keeping authentication and policy controls explicit.

Architecture overview

flowchart LR
  C[Client or Agent in Company B] --> B[Agent GW 2\nMCP Surface B]
  B -->|Gateway connection routing| A[Agent GW 1\nMCP Surface A]
  A -->|Target endpoint| M[MCP backend service]

  subgraph Auth checks
    S1[Source auth on Surface A]
    T1[Target auth injection on Surface B or A]
  end

  B --> T1
  A --> S1

Authentication model: source vs target

• Source authentication: validates who is calling a surface on inbound traffic.
• Target authentication: injects credentials on outbound traffic before forwarding to a target endpoint.

In GW-to-GW MCP flows, use this mental model:

1. Agent GW 2 receives a request on MCP surface B.
2. Agent GW 2 may inject target auth credentials (header secret) before forwarding.
3. Agent GW 1 receives the request on MCP surface A and enforces source auth (if configured).
4. If source auth passes, Agent GW 1 forwards to the MCP backend.
5. MCP backend logs show request and any injected header values expected by your test.

Prerequisites

• You already connected Agent GW 1 and Agent GW 2 and see the connection as Active.
• Both gateways have MCP surfaces created:
  • Surface A on Agent GW 1
  • Surface B on Agent GW 2
• MCP backend service reachable from Agent GW 1 target endpoint.
• You can view:
  • Gateway logs/monitoring
  • MCP backend logs
• Test credential prepared:
  • API key value keyA

Baseline configuration

1. Configure Agent GW 1 MCP surface A

1. Open MCP surface A.
2. Set protocol to MCP (if not already).
3. Configure target endpoint to your MCP backend.
4. Optional for auth scenarios:
   • Enable Source Authentication with API key mode.
   • Configure extraction header (example: X-API-Key) and expected key keyA.

2. Configure Agent GW 2 MCP surface B

1. Open MCP surface B.
2. Set endpoint type to via Gateway Connection.
3. Select gateway connection pointing to Agent GW 1.
4. Select remote MCP surface A.
5. Optional for target auth scenarios:
   • Enable Target Authentication.
   • Select secret containing keyA.
   • Header name must match Agent GW 1 source-auth extraction header.
   • Header format example: {value}.

3. Logging baseline

Before scenario tests, confirm:

• A successful request produces one log trail on Agent GW 2 (outbound) and Agent GW 1 (inbound/forward).
• MCP backend logs include request receipt.

Scenario playbooks

Each scenario below is written as a runbook: setup, action, expected outcome, and validation checks.

Scenario 1: Target Authentication and secret injection

Given: Agent GW 1 MCP surface has target authentication configured for its backend.

When: A request is sent through Agent GW 1 MCP surface.

Then:

• Secret-derived header is injected before backend call.
• MCP backend logs include the expected header value.

Validate:

1. Send MCP request through Agent GW 1 MCP surface.
2. Confirm request succeeds.
3. Check backend log for expected auth header and value pattern.

Scenario 2: Gateway-to-Gateway communication

Given: Agent GW 2 is connected to Agent GW 1 and MCP surface B routes to MCP surface A.

When: Agent GW 2 sends a request to Agent GW 1.

Then:

• Request is processed successfully end to end.
• MCP backend logs are visible.

Validate:

1. Send request to Agent GW 2 MCP surface B.
2. Confirm response is success.
3. Confirm Agent GW 1 logs show routed inbound request.
4. Confirm MCP backend request log exists.

Scenario 3: Missing source authentication

Given: Agent GW 1 MCP surface A requires source authentication (API key).

When: Request is sent without API key.

Then:

• Response indicates authentication failure.

Validate:

1. Remove API key header from test request.
2. Send request through Agent GW 1 directly or through Agent GW 2 routing to A.
3. Confirm non-success status (authentication error, commonly 403 in gateway path).
4. Confirm Agent GW 1 logs show source auth rejection.

Scenario 4: Valid source authentication

Given: Agent GW 1 MCP surface A requires source authentication (API key).

When: Request is sent with valid API key.

Then:

• Request is processed successfully.

Validate:

1. Send request with correct X-API-Key: keyA (or your configured header).
2. Confirm success response.
3. Confirm Agent GW 1 logs show authenticated request.

Scenario 5: Cross-gateway request with valid API key

Given:

• Agent GW 1 MCP surface A requires keyA.
• Agent GW 2 MCP surface B has no source auth.

When: Agent GW 2 sends request to Agent GW 1 using keyA.

Then:

• Request succeeds.

Validate:

1. Send request to MCP surface B including configured header/value keyA.
2. Confirm response is success.
3. Confirm Agent GW 1 auth check passed.

Scenario 6: Cross-gateway request without API key

Given:

• Agent GW 1 MCP surface A requires keyA.
• Agent GW 2 MCP surface B has no source auth.

When: Agent GW 2 sends request without API key.

Then:

• Response indicates authentication error.

Validate:

1. Send request to MCP surface B with no API key.
2. Confirm non-success status.
3. Confirm Agent GW 1 logs show missing/invalid credential rejection.

Scenario 7: Target authentication configuration

Given:

• Agent GW 1 MCP surface A requires API key keyA.
• Agent GW 2 MCP surface B is configured with target auth using keyA.

When: Agent GW 2 sends request.

Then:

• Request succeeds without client manually adding API key on every call.

Validate:

1. Configure target auth on MCP surface B with secret keyA.
2. Send request to MCP surface B.
3. Confirm success response.
4. Confirm Agent GW 1 source auth accepted request.

Scenario 8: Incorrect authentication configuration

Given:

• Agent GW 1 MCP surface A requires API key keyA.
• Agent GW 2 MCP surface B has incorrect auth configuration.

When: Request is sent.

Then:

• Response is 403 or equivalent authentication failure.

Validate:

1. Misconfigure one field intentionally (wrong header name, wrong secret, wrong format).
2. Send request.
3. Confirm failure status.
4. Confirm logs identify auth mismatch on Agent GW 1.

Confirm

Test 1: cross-gateway request without source auth key returns 403

From Scenario 3 or Scenario 6, Agent GW 1 should have returned a non-success auth error when the API key header was absent. Confirm Agent GW 1 logs show a source auth rejection for that request.

Test 2: cross-gateway request with valid source auth succeeds end-to-end

From Scenario 4 or Scenario 5, the request with the correct API key header should have succeeded. Confirm that Agent GW 2, Agent GW 1, and the MCP backend all show the request reaching the backend.

Test 3: target auth injection is visible in backend logs

From Scenario 1 or Scenario 7, the MCP backend logs should include the expected auth header and its value. If the header is absent, target auth is not configured on the correct hop.

Logging and observability

Use logs from three places for every test:

1. Agent GW 2 logs: request accepted, routing decision to gateway connection, outbound attempt.
2. Agent GW 1 logs: source auth pass/fail, inbound handling, forward decision.
3. MCP backend logs: request arrival and expected injected header behavior.

Best practices:

• Keep a consistent correlation key in request payload/metadata for traceability.
• Validate both status code and log trail before marking a test as passed.
• Store auth-related logs in your runbook evidence for operational audits.

Troubleshooting

Implementation notes from field experience

• Start with one strict auth boundary first (source auth on Agent GW 1), then layer target auth injection.
• Use one canonical API key per scenario set during initial testing to reduce false negatives.
• Keep header naming explicit and documented across teams. Most cross-company failures come from header mismatch, not routing.
• Validate with logs at every hop, not just response status.

Next steps

• Connect two gateways: review the connection setup if any gateway-level failures were encountered during scenario testing.
• Apply OPA policies to your gateway and surfaces: add OPA Rego access control rules on top of the auth configuration you have validated.

Related

• Connect two gateways: create and approve the gateway connection tunnel first.
• API keys: Create and rotate API keys.
• Secrets: Store credentials used by target authentication.
• Observability: Understand how to monitor runtime request and auth behaviour.