<a id="rtce-get-started"></a>

# Get Started with the Real-Time Context Engine in Confluent Cloud

Enable the Real-Time Context Engine on an Apache Kafka® topic, connect an AI agent, and
run your first query.

## Prerequisites

You need the following to get started with the Real-Time Context Engine:

- A Basic, Standard, Enterprise, or Dedicated
  Kafka cluster on Confluent Cloud. The cloud provider must be AWS, and the cluster
  must be hosted in a [supported region](../../get-started/regions.md#providers-regions).
- A Kafka topic with a registered schema (Avro, Protobuf, or JSON Schema).
- The following roles, at minimum:
  - CloudClusterAdmin or ResourceOwner (on the topic) to enable the
    Real-Time Context Engine on a topic.
  - DeveloperRead (on the Kafka cluster) to query data.
  - DeveloperRead (on the Schema Registry cluster) to list topics and get metadata.

#### NOTE
**Upsert mode requirements**

If your topic’s `cleanup.policy` configuration includes
`compact`, Kafka retains only the latest record for each key,
and the Real-Time Context Engine automatically enables upsert mode to match. In
upsert mode, the Real-Time Context Engine uses the Kafka record key as the primary
key, which must use raw byte format. Structured key schemas
(Avro, Protobuf) are not supported in upsert mode.

For more information, see [Upsert mode](limitations.md#rtce-upsert-mode).

If you need to create a cluster and topic, see
[Quick Start](../../get-started/index.md#cloud-quickstart).

For full details on roles and permissions, see [Access Control](access-control.md#rtce-access-control).

<a id="rtce-enable-topic"></a>

## Enable the Real-Time Context Engine on a topic

After you enable the Real-Time Context Engine on a topic, Confluent Cloud materializes the
topic data so that AI agents can query it.

### Cloud Console

To enable the Real-Time Context Engine on a topic, complete the following steps.

1. Sign in to [Confluent Cloud](https://confluent.cloud).
2. From the navigation menu, select **Environments**
   and then select your environment.
3. Click **Clusters** and then select your cluster.
4. From the navigation menu, select **Topics**.
5. In the topics list, find the **Context engine** column
   and click the **Off** status link for the topic you want
   to enable.
6. In the **Real-Time Context Engine** side panel, verify
   that all prerequisite checks pass. If any check shows a
   warning, the toggle is disabled.
7. Toggle the Real-Time Context Engine on.
8. In the confirmation window, review the information and
   click **Turn on**.

   The status changes to **Turning on** while the data is
   materialized. When the process completes, the status
   changes to **On**.

After the Real-Time Context Engine is enabled, the side panel shows the topic
details, including the MCP endpoint URL, and it provides
options to download or copy the topic details. To reopen
the panel later, click **Details** in the **Context engine**
column.

### Confluent CLI

Use the following command to enable the Real-Time Context Engine on an
existing topic:

```bash
confluent rtce rtce-topic create \
  --cloud <cloud> \
  --region <region> \
  --topic-name <topic_name> \
  --description "<topic_description>"
```

The following command-specific flags are supported:

* `--cloud`: Required. The cloud provider. Set to
  `aws`.
* `--region`: Required. The AWS region of the cluster.
* `--topic-name`: Required. The name of the Kafka topic
  to enable.
* `--description`: Optional. A description of the
  topic data.

The following example enables the Real-Time Context Engine on a topic:

```bash
confluent rtce rtce-topic create \
  --cloud aws \
  --region us-west-2 \
  --topic-name orders_topic \
  --description "Customer orders table"
```

### Confluent Cloud APIs

Send a POST request to enable the Real-Time Context Engine on a topic:

```bash
curl -X POST \
  https://api.confluent.cloud/rtce/v1/rtce-topics \
  -H "Content-Type: application/json" \
  -u "<api_key>:<api_secret>" \
  -d '{
    "spec": {
      "cloud": "<cloud>",
      "description": "<topic_description>",
      "environment": {"id": "<env_id>"},
      "kafka_cluster": {"id": "<lkc_id>"},
      "region": "<region>",
      "topic_name": "<topic_name>"
    }
  }'
```

The following request body parameters are supported:

* `cloud`: Required. The cloud provider. Set to
  `AWS`.
* `region`: Required. The AWS region of the cluster.
* `topic_name`: Required. The name of the Kafka topic
  to enable.
* `environment.id`: Required. The ID of the Confluent Cloud
  environment.
* `kafka_cluster.id`: Required. The ID of the Kafka
  cluster.
* `description`: Optional. A description of the topic
  data.

The following example enables the Real-Time Context Engine on a topic:

```bash
curl -X POST \
  https://api.confluent.cloud/rtce/v1/rtce-topics \
  -H "Content-Type: application/json" \
  -u "$KEY:$SECRET" \
  -d '{
    "spec": {
      "cloud": "AWS",
      "description": "Customer orders table",
      "environment": {"id": "env-abc123"},
      "kafka_cluster": {"id": "lkc-abc123"},
      "region": "us-west-2",
      "topic_name": "orders_topic"
    }
  }'
```

To verify that the topic was enabled, send a GET
request:

```bash
curl -X GET \
  "https://api.confluent.cloud/rtce/v1/rtce-topics?environment=<env_id>&spec.kafka_cluster=<lkc_id>" \
  -u "$KEY:$SECRET"
```

### Terraform

Use the [confluent_rtce_topic](https://registry.terraform.io/providers/confluentinc/confluent/latest/docs/resources/confluent_rtce_topic)
resource to enable the Real-Time Context Engine on a topic:

```terraform
resource "confluent_rtce_topic" "example" {
  cloud = "<cloud>"
  description = "<topic_description>"
  environment {
    id = "<env_id>"
  }
  kafka_cluster {
    id = "<lkc_id>"
  }
  region = "<region>"
  topic_name = "<topic_name>"
}
```

The following arguments are supported:

* `cloud`: Required. The cloud provider. Set to
  `"AWS"`.
* `region`: Required. The AWS region of the cluster.
* `topic_name`: Required. The name of the Kafka topic
  to enable.
* `environment.id`: Required. The ID of the Confluent Cloud
  environment.
* `kafka_cluster.id`: Required. The ID of the Kafka
  cluster.
* `description`: Optional. A description of the topic
  data.

The following example enables the Real-Time Context Engine on a topic:

```terraform
resource "confluent_rtce_topic" "example" {
  cloud = "AWS"
  description = "Customer orders table"
  environment {
    id = "env-abc123"
  }
  kafka_cluster {
    id = "lkc-abc123"
  }
  region = "us-west-2"
  topic_name = "orders_topic"
}
```

For all options for enabling and managing
topics with the Real-Time Context Engine, see
[Manage Real-Time Context Engine Topics](manage-topics.md#rtce-manage-topics).

## Create an API key

To connect an AI agent to the Real-Time Context Engine, you need a Global API
key. A Global API key provides access across Confluent Cloud resources
with a single credential. For more information, see
[Global API keys](../../security/authenticate/workload-identities/service-accounts/api-keys/overview.md#cloud-global-api-keys).

### Create a Global API key

To create a Global API key, use one of the following methods.

### Cloud Console

1. Open the Administration menu in the upper-right corner
   and select **API keys**.
2. Click **+ Add API key**.
3. For **Name**, enter a name for the API key.
4. Optionally, for **Description**, enter a description.
5. Under **Select account**, select **My account**.
6. Under **Select key scope**, select **Global**.
7. Click **Create API key**.
8. Download or copy the API key and secret. After you close
   this dialog, the secret is no longer available.

### Confluent CLI

Run the following command to create a Global API key for a
service account.

```bash
confluent api-key create \
  --resource global \
  --service-account <service_account_id> \
  --description "Global API key for the Real-Time Context Engine"
```

Save the API key and secret that the command returns. The
secret is not displayed again.

### Confluent Cloud APIs

Send a POST request to create a Global API key.

```bash
curl -X POST "https://api.confluent.cloud/iam/v2/api-keys" \
  -H "Authorization: Bearer $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "display_name": "my-global-key",
      "description": "Global API key for the Real-Time Context Engine",
      "owner": {"id": "<service_account_id>"},
      "resource": {"id": "global"}
    }
  }'
```

Save the API key and secret from the response. The secret is
not retrievable after the initial response.

<a id="rtce-generate-token"></a>

### Generate the Base64 token

The Real-Time Context Engine authenticates MCP requests with HTTP Basic
authentication, which requires a Base64-encoded token. Set
your API key and secret as environment variables, then
encode them to generate the token.

```bash
export KEY=<api_key>
export SECRET=<api_secret>
export TOKEN=$(echo -n "${KEY}:${SECRET}" | base64 | tr -d '\n')
echo $TOKEN
```

Use the resulting token in the `Authorization` header for MCP
requests:

```text
Authorization: Basic <token>
```

The Real-Time Context Engine also supports OAuth authentication. For details, see
[Access Control](access-control.md#rtce-access-control).

## Connect an AI agent

After you enable the Real-Time Context Engine on a topic, you can connect an AI
agent to query the data.

<a id="rtce-get-mcp-url"></a>

### Get the MCP endpoint URL

The MCP endpoint URL for your cluster follows this format:

```text
https://mcp.<region>.aws.confluent.cloud/mcp/v1/context-engine/organizations/<org_id>/environments/<env_id>/kafka-clusters/<lkc_id>
```

Replace the following placeholders:

- `<region>`: The AWS region of your cluster, for example
  `us-west-2`.
- `<org_id>`: Your Confluent Cloud organization ID.
- `<env_id>`: Your Confluent Cloud environment ID.
- `<lkc_id>`: Your Kafka cluster ID.

You can also find the endpoint URL in the Confluent Cloud Console by
completing the following steps:

1. Navigate to **Topics**.
2. In the **Context engine** column, click **Details** for your
   topic to open the **Real-Time Context Engine** side panel.
3. Click **Copy topic details to clipboard**.

The copied details include the topic name, environment, cluster,
cloud, region, and endpoint URL.

#### NOTE
If you connect to the Real-Time Context Engine over a private network, the
endpoint format differs from the public endpoint shown above.
For endpoint formats by networking option, see
[Private Networking](private-networking.md#rtce-private-networking).

### Configure an MCP client

Use the MCP endpoint URL and the Base64 token you generated
earlier to configure your MCP client.

#### Configure Claude Code

To add the Real-Time Context Engine MCP server in Claude Code, run the following
command:

```bash
claude mcp add --transport http \
  confluent-rtce \
  <mcp_endpoint_url> \
  --header "Authorization: Basic <token>"
```

Replace the following placeholders:

- `<mcp_endpoint_url>`: The MCP endpoint URL for your
  cluster. See [Get the MCP endpoint URL](#rtce-get-mcp-url)
  for the URL format and how to find it.
- `<token>`: The Base64 token you generated in
  [Generate the Base64 token](#rtce-generate-token).

#### Configure any MCP client

Any MCP client that supports streamable HTTP transport can
connect to the Real-Time Context Engine. Configure your client with the
following settings:

```json
{
  "mcpServers": {
    "confluent-rtce": {
      "url": "https://mcp.<region>.aws.confluent.cloud/mcp/v1/context-engine/organizations/<org_id>/environments/<env_id>/kafka-clusters/<lkc_id>",
      "headers": {
        "Authorization": "Basic <token>"
      }
    }
  }
}
```

## Run your first query

After your MCP client is connected, your AI agent has access to
three MCP tools: `listTopics`, `getMetadata`, and
`queryData`. You can interact with these tools through
natural language prompts.

Try the following prompts to explore your data:

- “What topics are available?”
- “Describe the schema for my topic.”
- “Show me the 10 most recent records in my topic.”

The AI agent translates your prompts into the appropriate MCP
tool calls and returns the results.

For the full set of supported query patterns, including filters,
ranges, and predicates with compound logic, see
[Query Data](query-data.md#rtce-query-data).

## Next steps

- [Query Data](query-data.md#rtce-query-data) - Learn about supported
  query patterns and MCP tools.
- [Manage Topics](manage-topics.md#rtce-manage-topics) - Enable, disable,
  and configure topics.

#### NOTE
This website includes content developed at the [Apache Software Foundation](https://www.apache.org/)
under the terms of the [Apache License v2](https://www.apache.org/licenses/LICENSE-2.0.html).