# How the Feast Python Feature Server Works: Architecture and Configuration Guide

> Understand the Feast Python feature server architecture and configuration. Learn how to set up and run this gRPC service for real-time and batch feature retrieval via feast listen or programmatically.

- Repository: [Feast/feast](https://github.com/feast-dev/feast)
- Tags: architecture
- Published: 2026-03-01

---

**The Feast Python feature server is a gRPC service that exposes `FeatureStore` methods for pushing streaming features, writing batches to online stores, and retrieving real-time features, configured via the `feature_server` block in [`feature_store.yaml`](https://github.com/feast-dev/feast/blob/main/feature_store.yaml) and started via the `feast listen` CLI command or programmatically using `get_grpc_server`.**

The Python feature server in Feast (feast-dev/feast) provides a production-ready gRPC interface that bridges external data producers and machine learning models with the underlying `FeatureStore`. This component enables low-latency feature retrieval and stream processing without requiring direct Python client access to the store backends, handling request routing, registry refresh, and protocol translation.

## Architecture of the Python Feature Server

### Core Components

The server implementation consists of three primary layers defined in [`sdk/python/feast/infra/contrib/grpc_server.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/infra/contrib/grpc_server.py):

- **`GrpcFeatureServer`** – The main servicer class that implements the gRPC API methods `Push`, `WriteToOnlineStore`, and `GetOnlineFeatures`. It acts as a thin wrapper that forwards incoming requests to the underlying `FeatureStore` instance (`fs`).
- **`get_grpc_server`** – A factory function that constructs a `grpc.Server`, registers the `GrpcFeatureServer` servicer, and attaches a health-checking servicer for Kubernetes or load balancer health probes.
- **`FeatureStore`** ([`sdk/python/feast/feature_store.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/feature_store.py)) – The core object that knows the online/offline stores, registry, and materialization logic. All server RPCs delegate to its methods: `push()`, `write_to_online_store()`, and `get_online_features()`.

### Request Flow

The server handles three primary request types:

1. **Push** – Streaming feature sources (e.g., Kafka) send a `PushRequest` containing a dictionary of feature values. `GrpcFeatureServer.Push` parses the dict into a pandas `DataFrame`, determines the push target (`online`, `offline`, or both), and invokes `FeatureStore.push`.
2. **WriteToOnlineStore** – A legacy endpoint that writes a single batch directly to the online store via `FeatureStore.write_to_online_store`. This is maintained for backward compatibility with older Feast clients.
3. **GetOnlineFeatures** – Model servers or notebooks send a `GetOnlineFeaturesRequest`. `GrpcFeatureServer.GetOnlineFeatures` resolves the requested features (or a feature service) and calls `FeatureStore.get_online_features`, returning a protobuf-encoded response.

The server also runs a background timer (`_async_refresh`) that periodically refreshes the feature registry so that new feature definitions become visible without requiring a process restart.

## Configuring the Python Feature Server

### feature_store.yaml Configuration

Feature-server settings are declared under the top-level `feature_server` key in [`feature_store.yaml`](https://github.com/feast-dev/feast/blob/main/feature_store.yaml). Omitting this key disables the server. When present, the configuration selects a concrete implementation and defines implementation-specific parameters:

```yaml
feature_server:
  type: local               # or "mcp"

  enabled: true             # optional, default false

  transformation_service_endpoint: localhost:6569   # for local server

  # mcp-specific options

  mcp_enabled: false
  mcp_server_name: feast-mcp-server
  mcp_server_version: "1.0.0"
  mcp_transport: null

```

The `type` field determines which configuration class is instantiated. Feast currently supports two built-in types:

- **`local`** – Uses `LocalFeatureServerConfig` defined in [`sdk/python/feast/infra/feature_servers/local_process/config.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/infra/feature_servers/local_process/config.py). This is the standard gRPC server for single-process deployments.
- **`mcp`** – Uses `McpFeatureServerConfig` defined in [`sdk/python/feast/infra/mcp_servers/mcp_config.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/infra/mcp_servers/mcp_config.py). This enables the Model Context Protocol (MCP) for integration with MCP-compatible clients.

### Configuration Validation

When the repository configuration is parsed, `RepoConfig` (see [`sdk/python/feast/repo_config.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/repo_config.py)) validates the `feature_server` dictionary. It resolves the concrete config class via `get_feature_server_config_from_type` and instantiates it, storing the result in `RepoConfig.feature_server`.

**Note:** Feast does not currently support custom server implementations—only the two built-in types (`local` and `mcp`) are loadable through this configuration mechanism.

## Starting the Python Feature Server

### CLI Method

The primary user-facing entry point is the `listen` command in [`sdk/python/feast/cli/cli.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/cli/cli.py). This command loads the repository configuration, instantiates a `FeatureStore`, builds the gRPC server using `get_grpc_server`, and blocks until termination:

```bash
feast listen \
  --address localhost:50051 \
  --max_workers 10 \
  --registry_ttl_sec 5

```

The arguments map directly to gRPC server parameters:
- `--address`: The host and port to bind to.
- `--max_workers`: The number of worker threads in the gRPC thread pool.
- `--registry_ttl_sec`: The interval for the background registry refresh timer.

### Programmatic Method

For embedded deployments or custom orchestration, you can start the server directly from Python without invoking the CLI. Import `get_grpc_server` from [`sdk/python/feast/infra/contrib/grpc_server.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/infra/contrib/grpc_server.py) and pass an initialized `FeatureStore`:

```python
from feast import FeatureStore
from feast.infra.contrib.grpc_server import get_grpc_server

store = FeatureStore(repo_path="my_repo")
server = get_grpc_server(
    address="localhost:50051",
    fs=store,
    max_workers=8,
    registry_ttl_sec=10,
)
server.start()
server.wait_for_termination()

```

This approach is useful when integrating the feature server into larger Python applications or when running within containerized environments where direct CLI access is limited.

## Summary

- The **Python feature server** is a gRPC bridge between external clients and the `FeatureStore`, implemented in [`sdk/python/feast/infra/contrib/grpc_server.py`](https://github.com/feast-dev/feast/blob/main/sdk/python/feast/infra/contrib/grpc_server.py).
- It exposes three primary RPCs—**`Push`**, **`WriteToOnlineStore`**, and **`GetOnlineFeatures`**—that delegate to `FeatureStore` methods for streaming ingestion, batch writes, and real-time retrieval.
- Configuration occurs via the **`feature_server`** block in [`feature_store.yaml`](https://github.com/feast-dev/feast/blob/main/feature_store.yaml), supporting **`local`** (standard gRPC) and **`mcp`** (Model Context Protocol) types validated by `RepoConfig`.
- Start the server using the **`feast listen`** CLI command or programmatically via **`get_grpc_server`**, specifying the bind address, worker threads, and registry refresh interval.

## Frequently Asked Questions

### What is the difference between the local and MCP Python feature server types?

The **local** type (`LocalFeatureServerConfig`) runs a standard gRPC server suitable for single-process deployments and direct client connections. The **MCP** type (`McpFeatureServerConfig`) implements the Model Context Protocol, enabling integration with MCP-compatible clients and tools. The local type requires a `transformation_service_endpoint`, while the MCP type accepts parameters like `mcp_server_name` and `mcp_transport`.

### How does the Python feature server handle registry updates?

The server runs a background timer (`_async_refresh`) that periodically refreshes the feature registry from the configured source. The refresh interval is controlled by the `registry_ttl_sec` parameter passed to `get_grpc_server` or the `--registry_ttl_sec` CLI flag. This ensures that new feature definitions, entities, and feature services become visible to the server without requiring a process restart.

### Can I run the Python feature server without the transformation service?

Yes, but only if your feature views do not require on-demand transformations. The `transformation_service_endpoint` field in the local server configuration is only required when serving features that depend on the transformation service for computing on-demand features or executing Python-based transformations. For simple feature retrieval from pre-materialized online stores, you can omit this endpoint.

### What gRPC methods does the Python feature server expose?

The `GrpcFeatureServer` class exposes three primary methods: **`Push`** for ingesting streaming features into online or offline stores, **`WriteToOnlineStore`** for batch writing legacy feature data directly to the online store, and **`GetOnlineFeatures`** for real-time feature retrieval by entity keys. These methods correspond to the `FeatureStore` methods `push()`, `write_to_online_store()`, and `get_online_features()`.