FeatureQL with AI

FeatureQL is typed, named, and composable — a safer surface for an LLM than raw SQL. Choose one of these three setups to give an assistant FeatureQL tools, from a sandbox library to a local MCP server with shared definitions.

There is no FeatureMesh-hosted MCP or FeatureMesh-operated execution of your SQL. The MCP server and SQL executor run where you control them. In managed-registry mode, FeatureQL definitions and catalog metadata go to FeatureMesh, but query rows do not. Your AI client may still send tool inputs and returned rows to its model provider; apply that provider's data policy and access controls.

1. Pip library in the assistant's sandbox

This is the fastest path when the assistant can install packages in a Python 3.12-or-newer environment.

Ask it to install FeatureMesh for batch work:

pip install featuremesh
bash

Or define the serving extra when you also want the embedded real-time path:

pip install "featuremesh[serving]"
bash

Then a local BatchClient is enough — no account, no server:

from featuremesh import BatchClient

client = BatchClient()
result = client.query("RETURN F := 1;")
print(result.dataframe)
python

Local feature definitions persist in ./featuremesh.db for as long as the sandbox filesystem survives. The default DuckDB executor is in memory, and the sandbox can access only the data you place in it. Use this path for learning and isolated work, not for data or state that must survive an ephemeral environment.

Details: Python library .

2. Local MCP + embedded registry (persist across sessions)

Run MCP on your machine when an AI client needs tool calling and feature definitions should persist on your filesystem.

Install the server extra:

pip install "featuremesh[server]"
bash

Save this as mcp_server.py:

from featuremesh import Backend, BatchClient, RegistryDeployment, set_default
from featuremesh.server import create_batch_client_mcp

set_default("registry", RegistryDeployment.LOCAL)
set_default("local.db_path", "./featuremesh.db")

client = BatchClient()
mcp = create_batch_client_mcp(
    {Backend.DUCKDB: client},
    host="127.0.0.1",
    port=8100,
)
mcp.run(transport="sse")
python

Start it:

python mcp_server.py
bash

Configure your AI client with the SSE endpoint http://127.0.0.1:8100/sse. Persisted feature definitions survive server restarts in featuremesh.db. The default DuckDB tables are in memory and last only for the server process; use a file-backed or warehouse sql_executor when source data must persist.

Use this when:

  • One person (or one machine) owns the project
  • You care about continuity more than sharing a registry with colleagues
  • You want the model on your warehouse, not only on sandbox sample data
  • You want zero cloud account for the registry itself

3. Local MCP + managed registry (collaborate)

When several people should share feature definitions, keep MCP and SQL execution local but connect the client to the managed FeatureMesh registry. Get an access token from console.featuremesh.com .

In mcp_server.py, replace the local configuration and client construction with:

import os

import duckdb

from featuremesh import Backend, BatchClient, RegistryDeployment, set_default

set_default("registry", RegistryDeployment.MANAGED)

def query_duckdb(sql: str):
    return duckdb.sql(sql).df()

client = BatchClient(
    access_token=os.environ["FEATUREMESH_ACCESS_TOKEN"],
    backend=Backend.DUCKDB,
    sql_executor=query_duckdb,
)
python

Then start the same server with your token:

export FEATUREMESH_ACCESS_TOKEN="your_access_token"
python mcp_server.py
bash

What is managed: feature definitions, namespaces, and access control — the catalog your team shares.

What stays local: MCP and execution against DuckDB, your warehouse, or customer-operated serving. FeatureMesh does not execute the SQL or receive its result rows.

Use this when you want a shared, versioned feature graph without standing up a shared SQLite file.

For a containerized stack with HTTP, MCP, notebooks, sample data, and serving services already wired together, use the Demos Docker container or adapt the demos repo tools .

What to ask for

Give a business question, the grain of one result row, and where the data lives. Name persisted prefixes if the assistant should reuse them (FM.SALES.). Do not paste the documentation site into the prompt — ask the assistant to load help('mental_model') then help('getting_started'), and a topic tag only when needed (extend, related).

What to review

The assistant should validate before it queries. When you look at the result:

  • Errors: use the code and location; do not retry the same draft.
  • formatted_featureql: prefer that spelling over the first attempt.
  • Warnings: read the code before you accept an ACK token in a comment.
  • Rows: check grain and a few values yourself. query is not a test harness.

If the graph is large and the failure is unclear, ask the assistant to diagnose, then shrink to the failing feature. Method detail: Python library tools .

The assistant’s own loop is help('assistant_workflow').

Giving the model good FeatureQL context

Do not paste the whole documentation site into a prompt. Prefer the LLM help corpus:

With a client or MCP connected, the same pages come back from help('tag') / featuremesh_help. To run the documentation suite on your backends, see Conformance tests .

Next steps

Last update at: 2026/10/13 08:32:21