Skip to content

Commit 9160f1f

Browse files
authored
docs(ai-gateway): certificates and ca_certificates on MCP Servers and Agents (AI-223) (#7494)
1 parent 46cf60a commit 9160f1f

5 files changed

Lines changed: 102 additions & 0 deletions

File tree

‎app/_ai_gateway_entities/ai-agent.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,12 @@ faqs:
9292
signs each proxied request using static IAM credentials, environment auto-detection, or an assumed role. This
9393
is separate from [`access.auth_strategies`](#schema-aigateway-agent-access), which authenticates inbound
9494
clients rather than outbound requests to the upstream agent. See [Upstream authentication](#upstream-authentication).
95+
96+
- q: How do I connect to an upstream agent that requires mTLS or serves a certificate from a private CA?
97+
a: |
98+
Set [`config.certificates`](#schema-aigateway-agent-config-certificates) for mTLS, or [`config.ca_certificates`](#schema-aigateway-agent-config-ca-certificates) for a private CA.
99+
Both fields apply to `a2a` and `http` AI Agents and require {{site.ai_gateway}} 2.3 or later.
100+
See [Upstream TLS](#upstream-tls).
95101
---
96102

97103
## What is an AI Agent?
@@ -377,6 +383,23 @@ config:
377383
378384
`config.upstream` is available regardless of the AI Agent's [`type`](#schema-aigateway-agent-type); it applies to `a2a` and `http` Agents alike.
379385

386+
## Upstream TLS {% new_in 2.3 %}
387+
388+
{% include md/ai-gateway/v2/upstream-tls.md name='AI Agent' schema_prefix='schema-aigateway-agent-config' %}
389+
390+
These fields apply to both `a2a` and `http` AI Agents.
391+
392+
In the following example, the AI Agent presents the `agent-client-cert` certificate to the upstream and verifies the upstream against the `kongair-internal-root-ca` CA:
393+
394+
```yaml
395+
config:
396+
url: https://booking-agent.internal.kongair.com
397+
certificates:
398+
- agent-client-cert
399+
ca_certificates:
400+
- kongair-internal-root-ca
401+
```
402+
380403
## Attach AI Policies
381404

382405
To enforce security, transformation, or governance controls on agent traffic (for example, request validation, PII detection, request logging), attach [AI Policies](/ai-gateway/entities/ai-policy/) to the agent. Add policy names or IDs to the AI Agent's [`policies`](#schema-aigateway-agent-policies) field. Multiple AI Policies can attach to one AI Agent; each runs independently in the request lifecycle.

‎app/_ai_gateway_entities/ai-ca-certificate.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@ related_resources:
2929
url: /ai-gateway/entities/ai-sni/
3030
- text: AI Data Plane Certificate
3131
url: /ai-gateway/entities/ai-data-plane-certificate/
32+
- text: AI MCP Server entity
33+
url: /ai-gateway/entities/ai-mcp-server/
34+
- text: AI Agent entity
35+
url: /ai-gateway/entities/ai-agent/
3236
faqs:
3337
- q: How is an AI CA Certificate different from a {{site.base_gateway}} CA Certificate?
3438
a: |
@@ -39,6 +43,13 @@ faqs:
3943
authority, carries no private key, and is used to verify the certificate a client or an
4044
upstream server presents. An AI Certificate is an identity the data plane uses itself: it carries a private key and is
4145
presented to complete a TLS handshake.
46+
- q: Can AI MCP Servers and AI Agents use an AI CA Certificate to verify their upstreams?
47+
a: |
48+
Yes.
49+
Yes, in {{site.ai_gateway}} 2.3 and later.
50+
Reference one or more AI CA Certificates by name in the `config.ca_certificates` field of an [AI MCP Server](/ai-gateway/entities/ai-mcp-server/#upstream-tls) or [AI Agent](/ai-gateway/entities/ai-agent/#upstream-tls).
51+
The AI MCP Server or AI Agent then uses them to verify the upstream's certificate, which lets it connect to upstreams signed by a private or internal CA.
52+
If you don't set the field, the default trust store is used.
4253
---
4354

4455
## What is an AI CA Certificate

‎app/_ai_gateway_entities/ai-certificate.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ related_resources:
3131
url: /ai-gateway/entities/ai-vault/
3232
- text: AI Data Plane Certificate entity
3333
url: /ai-gateway/entities/ai-data-plane-certificate/
34+
- text: AI MCP Server entity
35+
url: /ai-gateway/entities/ai-mcp-server/
36+
- text: AI Agent entity
37+
url: /ai-gateway/entities/ai-agent/
3438
faqs:
3539
- q: How is an AI Certificate different from a {{site.base_gateway}} Certificate?
3640
a: |
@@ -62,6 +66,14 @@ faqs:
6266
No. The `key` and `key_alt` fields are write-only. They're accepted on create and update, but
6367
never returned by a read. Keep your own copy of any key you register, or store it in an
6468
[AI Vault](/ai-gateway/entities/ai-vault/) and register a reference to it instead of the literal value.
69+
70+
- q: Can AI MCP Servers and AI Agents present an AI Certificate to their upstreams?
71+
a: |
72+
Yes.
73+
Yes, in {{site.ai_gateway}} 2.3 and later.
74+
Reference the AI Certificate by name in the `config.certificates` field of an [AI MCP Server](/ai-gateway/entities/ai-mcp-server/#upstream-tls) or [AI Agent](/ai-gateway/entities/ai-agent/#upstream-tls).
75+
The AI MCP Server or AI Agent then presents it as its client certificate, which lets it connect to upstreams that require mutual TLS (mTLS).
76+
The AI Certificate must include a private key.
6577
---
6678

6779
## What is an AI Certificate?

‎app/_ai_gateway_entities/ai-mcp-server.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,12 @@ faqs:
105105
clients, and from [`config.server.tools_list_auth`](#schema-aigateway-mcpserver-config-server-tools-list-auth),
106106
which only authenticates the one-time fetch of an `upstream-server`'s tool list. See
107107
[Upstream authentication](#upstream-authentication).
108+
109+
- q: How do I connect to an upstream that requires mTLS or serves a certificate from a private CA?
110+
a: |
111+
Set [`config.certificates`](#schema-aigateway-mcpserver-config-certificates) for mTLS, or [`config.ca_certificates`](#schema-aigateway-mcpserver-config-ca-certificates) for a private CA.
112+
Both fields require {{site.ai_gateway}} 2.3 or later.
113+
See [Upstream TLS](#upstream-tls).
108114
---
109115

110116
## What is an AI MCP Server?
@@ -525,6 +531,24 @@ config:
525531
role_session_name: kong-ai-gateway
526532
```
527533
534+
## Upstream TLS {% new_in 2.3 %}
535+
536+
{% include md/ai-gateway/v2/upstream-tls.md name='AI MCP Server' schema_prefix='schema-aigateway-mcpserver-config' %}
537+
538+
These fields work in every [server mode](#server-modes) that connects to an upstream: `conversion-only`, `conversion-listener`, `passthrough-listener`, and `upstream-server`.
539+
They have no effect in `listener` mode, because a listener only aggregates tools from other AI MCP Servers and doesn't connect to an upstream itself.
540+
541+
In the following example, the AI MCP Server presents the `mcp-client-cert` certificate to the upstream and verifies the upstream against the `kongair-internal-root-ca` CA:
542+
543+
```yaml
544+
config:
545+
url: https://mcp.internal.kongair.com
546+
certificates:
547+
- mcp-client-cert
548+
ca_certificates:
549+
- kongair-internal-root-ca
550+
```
551+
528552
## ACL tool control
529553

530554
When exposing MCP servers through {{site.ai_gateway}}, you may need granular control over which authenticated [AI Consumers](/ai-gateway/entities/ai-consumer/) can discover and invoke specific tools. The MCP Server's ACL feature lets you define access rules at both the default level (which applies to all tools) and per-tool level (for fine-grained exceptions).
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
When {{include.name}} connects to an upstream (the server at [`config.url`](#{{include.schema_prefix}}-url)), it does so over TLS by default, without presenting a client certificate, and trusts only the certificate authorities (CAs) in the data plane's default trust store.
2+
Use the following fields in `config` when your upstream needs something different:
3+
4+
<!-- vale off -->
5+
{% table %}
6+
columns:
7+
- title: Use case
8+
key: use_case
9+
- title: Field
10+
key: field
11+
- title: What to reference
12+
key: reference
13+
rows:
14+
- use_case: |
15+
The upstream requires mutual TLS (mTLS), so {{include.name}} must prove its identity to the upstream.
16+
field: "[`config.certificates`](#{{include.schema_prefix}}-certificates)"
17+
reference: |
18+
One [AI Certificate](/ai-gateway/entities/ai-certificate/). It must include a private key.
19+
The field is an array, but accepts only one entry.
20+
- use_case: |
21+
The upstream serves a certificate signed by a private or internal CA that the data plane doesn't trust by default.
22+
field: "[`config.ca_certificates`](#{{include.schema_prefix}}-ca-certificates)"
23+
reference: |
24+
One or more [AI CA Certificates](/ai-gateway/entities/ai-ca-certificate/). Together, they replace the default trust store when {{include.name}} verifies the upstream.
25+
{% endtable %}
26+
<!-- vale on -->
27+
28+
You can use either field on its own, or both together.
29+
30+
To reference a certificate, create the AI Certificate or AI CA Certificate first, then enter its `name` in the field.
31+
The `name` of a certificate can't be changed after you create it, so the reference stays valid.
32+
If a referenced name doesn't exist, the API returns an `HTTP 400` error.

0 commit comments

Comments
 (0)