Dialogflow MCP Server
Wraps a Google Dialogflow ES food-ordering agent: detect_intent runs customer text through the agent to get the intent (new.order, order.add, order_remove, order.complete, track.order, menu.ask) plus extracted dishes and quantities, and logs the conversation turns. A second minimal server variant wraps a Dialogflow CX agent instead.
Backs the ordering flow with a PostgreSQL database: menu lookup, atomic order placement (item lookup, duplicate merging, order row and line items in one transaction with caps), order tracking with an allowlisted field set for non-admin callers, plus conversation logging and health/readiness checks.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Dialogflow MCP Server
A Model Context Protocol (MCP) server that turns a Google Dialogflow ES food-ordering agent and its PostgreSQL backend into tools any AI client can call. Claude, Cursor or your own LLM app can understand a customer's message through Dialogflow, look up the menu, place an atomic order and track it, all through standard MCP tool calls. The remote server runs over Streamable HTTP with Bearer-token auth and a separate admin role, and keeps every database and Google credential on the server. The Dialogflow agent is versioned as code and measured with an NLU eval harness.
NLU results (intent accuracy, v1.1.0 agent, production): dev set 99.5% (211/212); held-out set 88.9% (48/54).
v1.0.0 agent | v1.1.0 agent | |
Dev set, the original 182 cases | 98.4% (179/182) | 99.5% (181/182) |
Dev set, all 212 cases (30 added in 1.1.0) | 99.5% (211/212) | |
Held-out set, 54 cases | 87.0% (47/54) | 88.9% (48/54) |
Held-out set without | 86.8% (46/53) | 88.7% (47/53) |
The dev set was used to find and fix the failures (73.6% before the v1.0.0 fixes), so its number is not a generalisation estimate; the held-out set (54 utterances, written separately from the dev set and never tuned on) is. The held-out gain is a single utterance from one run, so read it as "about the same", not as an improvement. One held-out utterance, "thats all thanks", became a training phrase in 1.1.0 by coincidence (it already passed before), so the table also gives the held-out numbers without it. Still wrong in the NLU layer: mixed quantities such as "a kota and 2 bunny chows" come back as number: [2] instead of [1, 2]. This fails the dev happy path ("2 bunny chows and a milk tart") and 2 of the 3 failing held-out conversations. Consumers should use order_line when the agent returns it, and otherwise not pair food_Item and number by position: treat a missing quantity as 1 or parse the quantities from the text. Details in NLU evals.
Live demo: nyiko.co.za/dialogflow-mcp
The demo domain is a South African food-ordering chatbot (Bunny Chow, Kota, Bobotie, Malva Pudding, ...), priced in rand. It grew out of my earlier NLP-Food project, a Dialogflow food-ordering chatbot with a FastAPI webhook and MySQL. This project replaces the webhook with MCP tools and PostgreSQL, and adds the remote server, its security model, the eval harness and the deployment.
Features
8 MCP tools over Dialogflow ES and Postgres: intent detection with conversation logging, menu lookup, atomic order placement, order tracking, and three admin tools. A second, minimal server wraps a Dialogflow CX agent (optional
cxextra).Three transports: stdio for local clients; Streamable HTTP (
/mcp) or legacy SSE (/sse) for the remote server.Two roles, fail closed: a required user token and an optional admin token, compared in constant time. Admin tools can only be registered through an
admin_tooldecorator that checks the role on every call; in remote mode a call without a request taggedadminis refused.track_orderreturns an allowlist of order fields to non-admin callers, so customer name, phone and address stay hidden.DNS-rebinding protection: Host and Origin allowlists on every endpoint except the health probes.
Atomic, bounded orders: item lookup, duplicate merging, the order row and all line items in one transaction, with caps on entries, distinct items and quantities.
Clean errors: inputs are validated before they reach Dialogflow or Postgres, and any database error reaches the client only as a generic "temporarily unavailable" message.
Non-blocking: tools are
asyncand run blocking Postgres/Dialogflow calls in worker threads, so a slow call never stalls/healthor other clients.Liveness and readiness:
/healthand/ready(databaseSELECT 1plus required settings).Agent as code: the Dialogflow agent lives in
dialogflow/agent/with an export/restore script; the pre-fix agent is kept inevals/agents/baseline-2026-11-17/so the baseline can be reproduced.NLU evals: dev and held-out golden sets, confusion matrix, slot accuracy, per-tag results, latency, a training-phrase overlap check and a baseline regression gate in
evals/.Production packaging: multi-stage non-root Docker image, Railway configuration as code, Neon Postgres, CI (ruff, mypy, pytest on Python 3.10 and 3.14 with a real Postgres, Docker smoke test with an authenticated MCP
initialize), and tag-driven releases to GHCR with third-party actions pinned to commit SHAs.
Related MCP server: mcp-enterprise-starter
Architecture
flowchart LR
subgraph Clients
C1[Claude Code / Claude Desktop]
C2[Cursor / custom LLM app]
end
subgraph Server["dialogflow-mcp-server (Python, Starlette + FastMCP)"]
A[Bearer auth + Host/Origin checks]
T[MCP tools<br/>async, blocking work in worker threads]
H["/health, /ready"]
end
DF[Google Dialogflow ES agent<br/>intents + food_Item entity]
PG[(PostgreSQL<br/>menu, orders, conversation logs)]
P[Platform probes] -- "no token" --> H
C1 -- "stdio or HTTPS /mcp" --> A
C2 -- "HTTPS /mcp or /sse" --> A
A --> T
T -- "gRPC detect_intent" --> DF
T -- "psycopg 3 pool" --> PGA client sends the customer's text to detect_intent. Dialogflow returns the intent (new.order, order.add, order_remove, order.complete, track.order, menu.ask) and the extracted dishes and quantities, and the server logs the turn to Postgres. The client then calls the database tools to act on it: get_menu, complete_order, track_order. Webhook fulfilment in Dialogflow is off on purpose; the MCP client does the work through tools. See docs/ARCHITECTURE.md for the components, security model, data model and deployment topology.
Quick start
Prerequisites: Python 3.10+, uv, Docker, and a Google Cloud project with the Dialogflow API enabled and an ES agent (you can restore the one in dialogflow/agent/, see Dialogflow agent). mcp dev (the MCP Inspector) also needs Node.js, because it starts the Inspector with npx.
1. Local, over stdio
git clone https://github.com/Nyiko-M-Shabangu/dialogflow-mcp-server.git
cd dialogflow-mcp-server
uv sync
docker compose up -d # Postgres 17 on 127.0.0.1:5433: schema, menu, demo orders
gcloud auth application-default login # or set GOOGLE_APPLICATION_CREDENTIALS
# Try it in the MCP Inspector
GCP_PROJECT=your-gcp-project-id uv run mcp dev src/dialogflow_mcp/server_es.pyThe stdio servers fall back to the docker compose database (postgresql://mcp:mcp_local_dev@127.0.0.1:5433/dialogflow_mcp) when DATABASE_URL is unset; the remote server never does.
Add it to Claude Code:
claude mcp add food-ordering \
-e GCP_PROJECT=your-gcp-project-id \
-e DATABASE_URL=postgresql://mcp:mcp_local_dev@127.0.0.1:5433/dialogflow_mcp \
-- uv run --directory /path/to/dialogflow-mcp-server dialogflow-mcp-esor to Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"food-ordering": {
"command": "uv",
"args": ["run", "--directory", "/path/to/dialogflow-mcp-server", "dialogflow-mcp-es"],
"env": {
"GCP_PROJECT": "your-gcp-project-id",
"DATABASE_URL": "postgresql://mcp:mcp_local_dev@127.0.0.1:5433/dialogflow_mcp"
}
}
}
}The Python servers do not read .env themselves. Export variables in your shell, put them in the client's env block, or use uv run --env-file .env ....
For a Dialogflow CX agent: GCP_PROJECT=... DF_AGENT_ID=... uv run dialogflow-mcp (uv sync installs the CX client for development; with pip, install dialogflow-mcp-server[cx]). The CX server is a minimal example: it validates its configuration but not its inputs, and passes Dialogflow errors through.
2. Run with Docker
The remote server is published as a container image on GHCR:
docker run --rm -p 8000:8000 \
-e MCP_AUTH_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" \
-e DATABASE_URL="postgresql://mcp:mcp_local_dev@host.docker.internal:5433/dialogflow_mcp" \
-e GCP_PROJECT=your-gcp-project-id \
-e GOOGLE_APPLICATION_CREDENTIALS_JSON="$(cat /path/to/service-account-key.json)" \
ghcr.io/nyiko-shabangu/dialogflow-mcp-server:latest
curl http://127.0.0.1:8000/health # 200
curl http://127.0.0.1:8000/ready # 200 once the database answers and settings are completeOn Linux, host.docker.internal does not resolve by default, and the compose database listens on the host's loopback only. Use --network host (drop -p) with DATABASE_URL=...@127.0.0.1:5433/..., or point DATABASE_URL at a database the container can reach.
Or build it yourself: docker build -t dialogflow-mcp-server .. The image runs as a non-root user, binds 0.0.0.0:$PORT (default 8000) and has a HEALTHCHECK.
3. Remote, over HTTPS
MCP_AUTH_TOKEN="<user-token>" \
MCP_ADMIN_TOKEN="<admin-token>" \
MCP_ALLOWED_HOSTS="mcp.example.com" \
GCP_PROJECT=your-gcp-project-id \
DATABASE_URL="postgresql://..." \
uv run dialogflow-mcp-remote # or: uvicorn --factory dialogflow_mcp.remote_server:create_remote_appThe server speaks plain HTTP, so put it behind TLS (a PaaS such as Railway, or Caddy/nginx). Then connect a client:
claude mcp add --transport http food-ordering-remote https://mcp.example.com/mcp \
--header "Authorization: Bearer <user-token>"Claude Desktop can use a custom connector (URL https://mcp.example.com/mcp, header Authorization: Bearer <token>), or the mcp-remote bridge for servers only your machine can reach.
Configuration
See .env.example for a commented template.
Variable | Required | Default | Description |
| yes | GCP project that hosts the Dialogflow agent | |
| ADC | Service-account key content (JSON), for hosts without file mounts. Wins over | |
|
| Dialogflow region, e.g. | |
| draft | Dialogflow ES environment name | |
| CX only | Dialogflow CX agent id | |
| remote | stdio only: | Postgres connection string. The remote server refuses to start without it |
|
| psycopg pool size and wait timeout | |
|
| Ping each pooled connection when it is handed out. Costs one round trip per checkout; keeps the first query after an idle period (Neon suspends, proxies drop connections) from failing. | |
| remote | User Bearer token, at least 16 characters; the remote server will not start without it | |
| Optional admin Bearer token, at least 16 characters and different from | ||
|
| Register the admin tools. A blank value counts as unset. Explicitly falsy ( | |
|
|
| |
| public host | localhost only | Extra allowed |
| localhost only | Extra allowed | |
|
| Bind address and port of the remote server | |
|
| docker compose only |
Tools
Tool | Role | What it does |
| user | Sends the customer's text to Dialogflow ES; returns reply, intent, confidence, parameters ( |
| user | Available menu items with ZAR prices, optionally filtered by category |
| user | One item by exact or unambiguous partial name |
| user | Creates an order and its line items in one transaction; 1-50 per item, at most 20 distinct items |
| user | Status, items and total of an order. Customer name, phone and address only for admins |
| admin | Sets the status to one of |
| admin | Latest orders, optionally by status ( |
| admin | Logged turns, optionally for one session ( |
The CX server (dialogflow-mcp) exposes a single detect_intent tool that returns replies, intent, confidence, current page and parameters.
Security model
Secrets stay on the server. Clients hold only a Bearer token.
DATABASE_URLand the Google key live in the server's environment.Fail-closed startup. The remote server refuses to start without
MCP_AUTH_TOKENorDATABASE_URL, with a token shorter than 16 characters, with an admin token equal to the user token, with contradictory admin settings, or with an unusableGOOGLE_APPLICATION_CREDENTIALS_JSON. Error messages never contain token values.Two roles, checked inside the tools.
MCP_AUTH_TOKENcallers may use the customer tools. WithMCP_ADMIN_TOKENset, only that token may run the admin tools; other callers get a refusal and the server logs one line,admin_tool_denied tool=<name> role=<role>. In remote mode a call that does not carry a request taggedadminis refused, so the check does not depend on the SDK attaching the request (ADR 0001). A test fails if a new tool is neither declared public nor registered through@admin_tool. Both tokens are compared withhmac.compare_digest, always both, so timing does not reveal which matched. The admin tools stay visible intools/listfor user-token clients; they just refuse to run (ADR 0004).PII minimisation. Order ids are sequential, so
track_orderreturns only an allowlist of fields (order_id,total_price,order_status,created_at,updated_at, plus the line items) to non-admin callers (ADR 0002). HTTP tests check this with both tokens on both transports.DNS-rebinding protection. Host and Origin are checked against allowlists before the token on every endpoint except
/healthand/ready. WebSocket connections are closed.Input validation and clean errors. Session ids, text length, language codes, order ids, quantities and field lengths are validated before they reach Dialogflow or Postgres. SQL is parameterised, and
LIKEwildcards in user input are escaped. Dialogflow and database error details are not echoed to clients; database errors are logged asdatabase_error tool=<name> error=<class> sqlstate=<code>.Least privilege. The server's Google identity needs only Dialogflow API Client. Exporting or restoring the agent needs Dialogflow API Admin, which the server does not have.
Limits. Tokens are shared secrets, not per-user identities: there is no OAuth, no per-user audit trail and no rate limiting in the app. MCP sessions are not yet bound to the token that opened them (ADR 0007, proposed). TLS is the platform's job. In stdio mode the process trusts its local user, so admin tools are allowed. See Roadmap and SECURITY.md.
Testing
uv sync
uv run pytest -q # unit, remote-server and eval tests; DB tests are skipped
uv run ruff check && uv run ruff format --check && uv run mypyThe remote-server tests serve the real ASGI app with uvicorn in a subprocess and drive it over HTTP: tokens, roles, track_order field filtering per token, Host/Origin checks, /health and /ready, startup configuration errors, and a regression test that a slow tool call does not block /health or a second client.
The PostgreSQL integration tests run when TEST_DATABASE_URL is set. They drop and recreate the public schema before every test, so use a throwaway database:
docker run -d --name df-mcp-pytest -e POSTGRES_DB=dialogflow_mcp_test \
-e POSTGRES_USER=mcp -e POSTGRES_PASSWORD=x -p 55434:5432 postgres:17-alpine
TEST_DATABASE_URL=postgresql://mcp:x@localhost:55434/dialogflow_mcp_test uv run pytest -q
docker rm -f df-mcp-pytesttests/conftest.py refuses (an error, not a skip) a TEST_DATABASE_URL whose database name does not end in _test; whose host is missing or not localhost/127.0.0.1/::1; whose port is missing, 5433 (the compose default) or equal to POSTGRES_PORT; that names the same database as DATABASE_URL; or that uses hostaddr/service. With REQUIRE_DB_TESTS=1 (set in CI) a missing TEST_DATABASE_URL fails the run. The full suite has 496 tests: 416 run without a database and 80 need one.
NLU evals
evals/ measures how well the Dialogflow agent understands customers, independent of the MCP server.
Run | Set | Intent accuracy | Macro F1 | Case pass rate |
| Conversations |
Before (production, pre-fix agent) | dev, 182 cases | 73.6% | 0.62 | 69.2% | 81.8% | 9/16 |
After (production, fixed agent) | dev, 182 cases | 98.4% | 0.98 | 95.6% | 93.2% | 13/16 |
Re-run on staging (same agent) | dev, 182 cases | 98.4% | 0.98 | 95.6% | 93.2% | 13/16 |
Held-out (same agent, run once) | held-out, 54 cases | 87.0% | 0.85 | 77.8% | 68.0% | 2/5 |
v1.1.0 dev (production, v1.1.0 agent) | dev, 212 cases | 99.5% | 0.99 | 94.3% | 89.3% | 15/16 |
v1.1.0 dev, original cases only (same run) | dev, 182 cases | 99.5% | 96.7% | 94.3% | ||
v1.1.0 held-out (same agent, run once) | held-out, 54 cases | 88.9% | 0.88 | 79.6% | 68.0% | 2/5 |
How to read it:
The dev set guided the fixes. It is 212 labelled single-turn utterances (182 in v1.0.0, 30 added in 1.1.0) and 16 conversations covering slang, typos, multi-item orders, "a/an" quantities, off-menu dishes, menu questions and order ids. 13 of its utterances are, after normalising case and punctuation, also training phrases of the current agent (some were added as fixes). They are labelled
verbatim_in_training, and every report also gives the metrics without them: 76.6% → 98.2% intent accuracy on the other 171 cases in v1.0.0, and 99.5% on the other 199 cases in v1.1.0.The 1.1.0 agent update added the
menu.askintent, more completion phrases ("dats it", "no thats it") and typo and size synonyms ("vetcook", "a quarter bunny"). It was written against the dev set only; the private repository it was written in never contained the held-out set. The 30 new dev cases pass 24/30; the 6 failures are all mixed quantities. The conversationconv-09was relabelled because the quantity is optional with a default of 1 (the bot no longer asks "how many?"), so the conversation counts before and after 1.1.0 are not like-for-like.The held-out set did not. 54 single-turn utterances and 5 conversations in
evals/golden/heldout.yaml, written for this purpose by a writer who saw only the menu, the intent names and the label rules, not the training phrases or the dev set. The writer had no access to the repository, but its brief was written by someone who had seen the training phrases and the dev set, and it included a few style hints, some local dish nicknames and one example utterance, so the set is independent of the dev set but not perfectly blind. Every candidate with a near match to a training phrase or a dev-set utterance was dropped mechanically before the run (16 of 70;evals/leakage.py), and the agent was not changed afterwards. 87.0% (v1.0.0) and 88.9% (v1.1.0) are the numbers to expect on new phrasing; each is from one run of 54 utterances, so treat them as rough estimates. One documented overlap exists since 1.1.0:ho-complete-01("thats all thanks") is now also anorder.completetraining phrase. The held-out file is never edited, so the overlap is recorded inevals/leakage.py(any other near match still fails CI), and the table above gives the numbers without that case.Part of the gain is repair. In the baseline agent the Welcome intent's training phrases were the bot's own greeting texts, so "hi" fell through to the fallback (Welcome recall 0.00), and "a kota" was classified as a removal.
Known gaps (v1.1.0). "a"/"an" is not extracted as a quantity of 1 when it is mixed with digits or repeated ("a kota and 2 bunny chows" →
[2], "a milk tart and a vetkoek" →[1]): 9 of the 12 failing dev cases, the dev happy path ("2 bunny chows and a milk tart") and 2 of the 3 failing held-out conversations.@sys.numbercannot read "a", and a flatnumberlist cannot be aligned withfood_Item. In development runs on a staging candidate agent (reports not included here), a compositeorder_lineparameter fixed this; that agent is not promoted, anddetect_intentis already ready for it. Also failing: "1 bobotie and 2 burgers" (the off-menu quantity is kept), "track order one thousand and five" (read as 1000; the backend should parse number words if it matters), "also order 42" in a tracking context, and on the held-out set some slang dish names ("sphatlho"), "n" for "and" in removals, and tracking phrasings without the word "track".
The baseline agent is committed as evals/agents/baseline-2026-11-17/, so the 73.6% can be reproduced on a staging project (restore REPLACES that project's agent, and ES needs a minute or two to train):
uv run python scripts/dialogflow_agent.py restore --project <staging-project> --confirm <staging-project> --dir evals/agents/baseline-2026-11-17
uv run python evals/run_nlu.py --project <staging-project> # dev set, ~273 calls, ~3 min
# restore dialogflow/agent/ afterwards, then the held-out set:
uv run python evals/run_nlu.py --project <staging-project> --cases evals/golden/heldout.yaml --conversations evals/golden/heldout.yaml--dry-run prints the call plan without calling Dialogflow, and --project-label keeps the project id out of a report you intend to commit. .github/workflows/evals.yml runs the dev set against a staging project on demand and gates on a drop against the committed baseline.
CI
ci.yml runs on every push and pull request: ruff (lint and format), mypy, the golden-set overlap check, pytest on Python 3.10 and 3.14 against a Postgres 17 service container (the DB tests are required there), a package build, and a Docker build with a smoke test (/health 200, /ready 503 without a database, POST /mcp 401 without a token and 200 for an authenticated MCP initialize). release.yml runs on a v*.*.* tag: it checks that the tag matches the version in pyproject.toml, creates the GitHub Release from the matching CHANGELOG section, and only then publishes the GHCR image. Third-party actions are pinned to commit SHAs.
Deployment (example: Railway + Neon)
The reference deployment runs the container on Railway and the database on Neon serverless Postgres; both have free tiers that are enough for a demo. Any container host with TLS works the same way.
Database. Create a Neon project and run the schema once:
psql "<neon-connection-string>" -f db/init.sql(tables and the menu; idempotent). For a demo, also rundb/seed_demo.sql, which adds orders 1001-1004 with fictional customers; skip it for real use. Existing databases are upgraded with the files indb/migrations/, in order.Service. Create a Railway service from this repo. Railway builds the
Dockerfile; build, health check (/ready) and restart settings are kept as code in.railway/railway.ts(npm install --prefix .railway, thenrailway config plan/railway config apply).Variables. Set
MCP_AUTH_TOKEN(and optionallyMCP_ADMIN_TOKEN),MCP_ALLOWED_HOSTS=your-service.up.railway.app,DATABASE_URL(Neon's direct connection string; the server keeps its own small pool),GCP_PROJECTandGOOGLE_APPLICATION_CREDENTIALS_JSON(the whole key file content; Railway has no file mounts). Do not setHOST.Check.
curl https://your-service.up.railway.app/healthreturns 200,/readyreturns 200, andPOST /mcpwithout a token returns 401.
Free-tier notes: Neon suspends idle computes, so the first query after a pause is slower; the pool waits up to DB_POOL_TIMEOUT (10 s) for a connection. Dialogflow ES Trial edition text requests are free but rate-limited per minute. Keep the eval workflow manual.
Dialogflow agent
dialogflow/agent/ holds the "SA Food Ordering" ES agent: intents and training phrases, the food_Item entity (exactly the nine menu dishes, matching food_items.name), and contexts.
# pull an agent into dialogflow/agent/ (review the git diff afterwards)
uv run python scripts/dialogflow_agent.py export --project your-gcp-project-id --gcloud
# push dialogflow/agent/ into a project; this REPLACES that project's whole agent
uv run python scripts/dialogflow_agent.py restore --project your-gcp-project-id --confirm your-gcp-project-id --gcloudExport blanks the webhook URL and credentials and the legacy V1 key. Fulfilment is off, so every reply comes from static responses and the MCP client does the real work.
Intent | Parameters | Use |
| Greetings ("hi", "howzit", "sawubona") | |
| Start an order; sets the | |
|
| Add dishes; needs the |
|
| Remove dishes; needs |
| Finish the order ("that's all", "dats it"); needs | |
|
| Order status; prompts for the id when it is missing; sets |
|
| Another order id in an |
|
| Menu, price and availability questions, with or without an order in progress; a static menu reply, never adds to the order (new in 1.1.0) |
| Anything else, including off-menu dishes |
The number list can be shorter than the food_Item list ("a kota" has no number, and in "a kota and 2 bunny chows" it is [2]), and a number may arrive as a float (2.0) or a string ("1"). Do not pair the lists by position: treat a missing quantity as 1 or parse the quantities from the text. If the agent returns a composite order_line parameter (a list of {food_Item, number} pairs), detect_intent derives aligned flat food_Item and number from it (a missing number becomes 1) and also returns order_line unchanged; prefer order_line when it is present. The current agent does not return order_line yet.
Project structure
src/dialogflow_mcp/
server_es.py Dialogflow ES + PostgreSQL tools, admin gate (stdio entry point: dialogflow-mcp-es)
server.py Dialogflow CX detect_intent (stdio entry point: dialogflow-mcp)
remote_server.py Authenticated Starlette app: /mcp or /sse, /health, /ready (dialogflow-mcp-remote)
database.py psycopg 3 connection pool and query helpers
gcp_auth.py Google credentials from GOOGLE_APPLICATION_CREDENTIALS_JSON or ADC
db/init.sql Schema and menu; db/seed_demo.sql demo orders; db/migrations/ for upgrades
dialogflow/agent/ The Dialogflow ES agent as code
scripts/ Agent export/restore
evals/ NLU golden sets (dev, held-out), runner, metrics, overlap check, reports, baseline agent
tests/ Unit, remote-server (real uvicorn), DB integration and eval tests
docs/ ARCHITECTURE.md and architecture decision records (docs/adr/)
.railway/ Railway configuration as code
.github/workflows/ CI, release (GitHub Release + GHCR image) and manual NLU evalDesign decisions
The main decisions are recorded as ADRs in docs/adr/. "Accepted" means built and tested; "Proposed" means designed but not built.
ADR | Decision | Status |
Fail-closed admin check in remote mode, admin tools registered by construction | Accepted | |
Redact | Accepted | |
Constant-time comparison of the Authorization header against both tokens | Accepted | |
Keep | Accepted | |
| Accepted | |
CI on every push, database tests required in CI and guarded against the wrong database | Accepted | |
Bind each MCP session to the credential that opened it | Proposed | |
Plain single-line log handler in remote mode | Accepted |
Roadmap
Not built yet, in rough priority order:
Session-to-token binding (ADR 0007): tie each MCP session to the credential that opened it, so a leaked session id cannot be used with the other token.
Better quantity handling in the agent: promote a composite
order_lineparameter so "a"/"an" is read as 1 in multi-item orders (the MCP side is ready since 1.1.0). Measure on the held-out set, then write a fresh held-out set, because this one will have been looked at.Per-user identity: OAuth 2.1 (the MCP authorization spec) instead of shared tokens, with a per-user audit trail and token rotation without a redeploy.
Rate limiting in the app, or a gateway in front of it.
Keyless CI auth for the eval workflow: Workload Identity Federation instead of a service-account key in a GitHub secret.
Supply chain: pin the Docker base images by digest.
Configuration object: build the FastMCP server from a settings object instead of reading the environment at import time, which would let tests build several apps in one process.
Scale-out: MCP session state lives in one process today, so more than one replica needs sticky routing.
CX server: the same validation and error handling as the ES server, or more tools.
Contributing
Issues and pull requests are welcome; see CONTRIBUTING.md. Security reports: see SECURITY.md.
This project was developed in a private repository; its history was squashed into a single commit for the public release.
License
MIT © 2026 Nyiko Shabangu
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted PostgreSQL MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Build custom POS apps with your AI agent. Final's MCP server gives developers what they need to ship a custom point of sale: scaffold a checkout flow, adapt vetted screen blueprints for counter POS, self-checkout kiosks, restaurant ordering and payment terminals, ground every call in Final's version-locked POS APIs, validate, boot a live preview and deploy to real hardware with integrated card payments. The same server also manages the store behind it: products, stock, orders, customers and sales reports. Remote Streamable HTTP with OAuth 2.1.
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA production-grade MCP server and client implementation with comprehensive features including structured logging, health checks, metrics, authentication, and RAG capabilities with PostgreSQL vector search. Supports both stdio and SSE transports with containerization and security features for enterprise deployment.MIT
- AlicenseAqualityDmaintenanceA production-grade MCP server that gives AI agents safe, authenticated access to a PostgreSQL database.3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets restaurants operate their point-of-sale through an LLM agent — edit menus, 86 items, check sales, restock inventory, monitor voids, and more via twenty tools over both stdio and Streamable HTTP transports with per-request tenancy from API keys.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceMCP server exposing restaurant tools including search by cuisine, price, rating, and open status, restaurant details, user preferences stored in Neon Postgres, and RAG knowledge search covering 50 mock restaurants across Scottsdale and Phoenix.-