Model Context Protocol (MCP) — Operational Playbook for BMAD Workstreams

Scope: This guide replaces the older Spec Kit orientation with the current BMAD Method pipeline in
SMS+SQS/
. Every Codex CLI / IDE session shares the global configuration in
~/.codex/config.toml
, so keeping this file accurate guarantees the same toolbelt for all agents. Use it alongside:
SMS+SQS/bmad/core/*
— method definitions & guardrails
SMS+SQS/docs/runbooks/
— per-run acceptance evidence templates
SMS+SQS/docs/mcp-servers/
— deep dives and SOPs (update when workflows move)

1) Quick Decision Grid (BMAD checkpoints)

Server	Primary Capability	BMAD Phase Trigger	Inputs (lowest privilege first)	Outputs / Evidence	Notes
sequential_thinking	Structured reasoning trail & hypothesis revision	Blueprint / Mobilize: task scoping, acceptance planning	Thought payload ( `thought` , `nextThoughtNeeded` , `thoughtNumber` , etc.)	JSON summary of reasoning + stderr box log	No auth; suppress stderr boxes with `DISABLE_THOUGHT_LOGGING=true`
searxng	Multi-engine web search & article extraction	Blueprint / Mobilize: competitive research, standards lookup	Query text, pagination, language, safesearch	SERP JSON, cleaned markdown via `web_url_read`	Self-hosted at `http://localhost:8080` via Docker; swap to a public instance if the local stack is unavailable
semgrep	Local SAST scan & report tooling	Assemble / Deploy: before accepting implementation or PR	Absolute repo path ( `/home/work/workspace start/...` ), config ( `auto` , `p/ci` , etc.)	Findings JSON, rule listings, filtered/exported reports	CLI auto-installs if missing; now supports paths with spaces
chrome_devtools	Live browser, tracing, screenshots	Mobilize / Assemble when UI regression, perf capture, network triage	URL, optional launch args	Traces, screenshots, console logs	Requires local Chrome; mind secrets in browser context
playwright	Deterministic web automation	Mobilize / Assemble smoke paths, headless repro	URL + a11y selectors, origin allowlists	Snapshots, network logs, interactions	Node 20+; set `--allowed-origins` for prod URLs
context7	API/library documentation lookup	Blueprint / Assemble when resolving API drift	Library name or ID	Canonical doc excerpts, URL references	`CONTEXT7_API_KEY` already configured
github	Repo/PR/Issue orchestration	Deploy — branch hygiene, reviews, labels	PAT / OAuth (read-only by default)	File contents, PR status, review actions	Hosted remote; expand privileges only with approval
notion	Knowledge base read/write	Blueprint / Mobilize / Deploy — design sync, decision capture	Notion token, page/db ids	Page content, updates	Keep token least-privilege; follow workspace policy
supabase (disabled)	Read-only DB & docs	On demand for schema validation	Project ref, optional read token	SQL results, schema docs	Enable only when needed; keep read-only
logfire (disabled)	Observability / trace queries	Deploy triage of failing jobs	Logfire read token	Exception listings, trace links	Requires token; currently opt-in
vibe_check (disabled)	Guardrail reviewer	Optional “pattern interrupt” before PR	Provider tokens	Meta-feedback blocks	Enable when high-risk changes loom
pieces_lite	Local note store & recall	Retrospective knowledge reuse	Search query / note content	Stored notes, search hits	Persist lessons under `~/.local/share/pieces-lite`
markitdown (disabled)	Markdown conversion utilities	On demand	Files/blobs	Markdown output	Enable when documentation import needed

2) Global Operating Patterns

BMAD cadence awareness
- Blueprint: gather context (context7, searxng, notion) and codify acceptance via
```
sequentialthinking
```
  .
- Mobilize: attach evidence sources (context7 excerpts, searxng results, notion pages).
- Assemble: run automation (playwright, chrome_devtools) and hardening (semgrep).
- Deploy: coordinate reviews & releases (github, logfire if enabled), then persist outcomes (pieces_lite, notion).
Environment hygiene
All paths in this repo live under
```
/home/work/workspace start
```
. Semgrep’s server now quotes arguments so directories with spaces succeed. Keep environment variables in
```
~/.codex/mcp.env
```
and never hard-code secrets.
Approval policy
Current profile:
```
approval_policy="never"
```
,
```
sandbox_mode="danger-full-access"
```
. You must solve tasks without requesting escalations; remove any temporary tooling before exiting.

3) Per-Server Guidance & SOPs

3.1 Sequential Thinking (

sequentialthinking

) — Enabled

Command:

npx -y @modelcontextprotocol/server-sequential-thinking

(configured).

Tools:
```
sequentialthinking
```
(single tool).
Usage:
1. Kick off during BMAD Blueprint to make acceptance criteria explicit.
2. Increment
```
thoughtNumber
```
  ; update
```
totalThoughts
```
  when adding branches.
3. Capture JSON response and store in the relevant
```
docs/runbooks/*
```
  artifact.
Toggles: export
```
DISABLE_THOUGHT_LOGGING=true
```
to suppress the stderr box art when running in quiet environments.

Manual steps (if re-install required):

Run

npm install -g @modelcontextprotocol/server-sequential-thinking

or rely on NPX.

If offline, mirror the npm tarball (

https://registry.npmjs.org/@modelcontextprotocol/server-sequential-thinking/-/server-sequential-thinking-2025.7.1.tgz

3.2 SearXNG (

searxng_web_search

web_url_read

) — Enabled

Command:

npx -y mcp-searxng

with

SEARXNG_URL=http://localhost:8080

Best moments: confirm standards, gather policy references, competitor scans during Blueprint/Mobilize.
Operational tips:
- Use
```
web_url_read
```
  after
```
searxng_web_search
```
  to extract clean markdown for evidence.
- Keep
```
safesearch
```
  at
```
2
```
  for compliance, set
```
language="all"
```
  unless acceptance requires locale filtering.
Switching instances: if the local instance is unavailable, either restart docker compose or pick another public instance from https://searx.space/ from https://searx.space/ and update
```
~/.codex/config.toml
```
.
Self-host (full engine + browser integration) — cannot be automated here; follow these explicit steps:
1. Install Docker & Docker Compose.
2. ```
git clone https://github.com/searxng/searxng.git
```
  →
```
cd searxng
```
  .
3. Copy
```
searxng.example.yml
```
  to
```
searxng.yml
```
  .
4. Edit
```
searxng.yml
```
  : under
```
engines
```
  , set
```
enabled: true
```
  for every engine you wish to expose; under
```
ui
```
  , set
```
default_theme: simple
```
  .
5. In
```
docker-compose.yml
```
  , ensure
```
networks
```
  allow outbound https for all engines.
6. Launch with
```
docker compose up -d
```
  .
7. Verify at
```
http://localhost:8080
```
  : open the UI, go to Preferences → Engines, enable every engine (scroll to bottom to save).
8. Point Codex config to
```
SEARXNG_URL=http://localhost:8080
```
  .
9. For browser integration (Chrome/Firefox): install the SearXNG search plugin by navigating to
```
http://localhost:8080/opensearch.xml
```
  , click “Add search engine”, then choose it as default in browser settings.
BMAD tie-in: store SERP IDs or extracted markdown under
```
docs/runbooks/
```
for acceptance evidence.

3.3 Semgrep (

scan_directory

, etc.) — Enabled

Command:

node "/home/work/workspace start/tools/mcp/semgrep/build/index.js"

Enhancements made:
- ```
BASE_ALLOWED_PATH
```
  now resolves to
```
/home/work/workspace start
```
  , so full repo scans are accepted.
- Path and config arguments are JSON-quoted to handle spaces safely.

Standard flow:

Run

scan_directory

with

path="/home/work/workspace start/SMS+SQS"

and

config="p/ci"

before marking Assemble complete.

Use
```
export_results
```
to produce SARIF or markdown.
Persist logs under
```
docs/runbooks/task-ledger.md
```
.

Manual reinstall: from
```
tools/mcp/semgrep/
```
, run
```
pnpm install && npm run build
```
. Ensure
```
semgrep
```
CLI on PATH (pip install if absent).
SAST evidence: attach the JSON block from semgrep to BMAD acceptance packages.

3.4 Chrome DevTools & Playwright — Enabled

chrome_devtools
- ```
npx -y chrome-devtools-mcp@latest
```
  (stdio).
- Use for live debugging, capturing traces, verifying network anomalies.
- BMAD: Mobilize (reproduce) and Assemble (perf validation).
- Manual: ensure Chrome ≥ 119 installed; adjust
```
startup_timeout_sec
```
  for slow boot.
playwright
- ```
npx -y @playwright/mcp@latest
```
  .
- Use the
```
browser_*
```
  tools to run deterministic A11y-driven flows.
- Configure allowed origins when targeting staging/prod to respect security.
- BMAD: Mobilize (smoke plan), Assemble (automation evidence).

3.5 Documentation & Knowledge Agents

context7 — Already configured; feed library IDs via
```
codex mcp
```
tools when API drift suspected.
notion — Use to pull or push decisions. Confirm
```
NOTION_TOKEN
```
validity; scope to relevant workspace.
pieces_lite — Local Python server at
```
tools/mcp/pieces-lite/pieces_lite_server.py
```
.
- Tools:
```
pieces_store_note
```
  ,
```
pieces_search_notes
```
  ,
```
pieces_list_recent
```
  .
- BMAD: Deploy / retrospectives; capture gotchas once acceptance closes.
- Storage lives in
```
~/.local/share/pieces-lite
```
  ; do not version control.

3.6 Delivery / Governance

github — Remote HTTP server at
```
https://api.githubcopilot.com/mcp/
```
(read-only). Request additional toolsets only with approval.
supabase (disabled) — Enable when data validation is in scope; ensure
```
read_only=true
```
remains.
logfire (disabled) — For observability deep dives; requires
```
LOGFIRE_READ_TOKEN
```
.
vibe_check (disabled) — Great for complex redesigns; set
```
VIBE_CHECK_API_KEY
```
& provider tokens before enabling.
markitdown (disabled) — Activate for bulk doc conversions.

4) Enabling / Reconfiguring Servers (Human Steps Required)

Use these instructions when infrastructure credentials or GUI interaction is required. Follow exactly; each list is in “autistic detail” to avoid ambiguity.

SearXNG — Full self-host setup with maximum engines

Provision host with Docker & docker-compose (Linux):

sudo apt update && sudo apt install docker.io docker-compose-plugin

```
sudo usermod -aG docker $USER
```
(log out/in).

Fetch sources:

git clone https://github.com/searxng/searxng.git && cd searxng

Configuration file:
- Copy
```
searxng.example.yml
```
  →
```
searxng.yml
```
  .
- Open in editor; under
```
engines
```
  , set
```
enabled: true
```
  for every listed engine.
- Set
```
categories
```
  to include
```
general
```
  ,
```
images
```
  ,
```
news
```
  ,
```
science
```
  , etc., as desired.
- Under
```
outgoing
```
  , configure
```
request_timeout
```
  (e.g., 5s).
Docker compose: run
```
docker compose up -d
```
.
Enable via UI:
- Visit
```
http://localhost:8080
```
  .
- Click the hamburger menu → Preferences → Engines.
- Check “Enable all” (or manually toggle each engine).
- Scroll to the bottom, click Save.
Browser integration:
- In Chrome: visit
```
http://localhost:8080/opensearch.xml
```
  . When prompted, click Add to Chrome → confirm in the omnibox “Manage search engines” panel; set SearXNG as default.
- In Firefox: open the same URL → a banner appears → click Add “SearXNG” → open Settings → Search and select SearXNG as default.

Point Codex: edit

~/.codex/config.toml

to set

SEARXNG_URL="http://localhost:8080"

. Restart Codex CLI/IDE session.

Optional: configure API key restrictions or IP allowlists inside
```
searxng.yml
```
under the
```
server:
```
section if exposed externally.

Notion token rotation

Sign into https://www.notion.so/my-integrations.
Click + New integration → name it
```
SMS+SQS Codex Agent
```
.
Select workspace, set permissions to Read content and Update content.
Copy generated token; update
```
~/.codex/mcp.env
```
(
```
NOTION_TOKEN=...
```
).
In the Notion UI, share required pages/databases with the integration (••• menu → Add connections).

Reload MCP server (

codex mcp remove notion && codex mcp add notion -- npx -y @notionhq/notion-mcp-server@latest

GitHub server scope change (if write access needed)

Generate a PAT at https://github.com/settings/tokens with scopes
```
repo
```
,
```
workflow
```
(minimum).
Export as
```
GITHUB_PAT
```
in
```
~/.codex/mcp.env
```
.

Update

~/.codex/config.toml

if additional toolsets required (

env = { GITHUB_TOOLSETS="repositories,pulls,issues" }

Restart Codex session.

Supabase MCP enablement

Obtain project ref from Supabase dashboard (Settings → General → Project Reference).
For read-only access, create service key with “read-only” permissions.

Update

~/.codex/config.toml

block: set

enabled = true

, add

bearer_token_env_var

Export token into

~/.codex/mcp.env

(e.g.,

export SUPABASE_ACCESS_TOKEN=...

Run
```
codex mcp list
```
to confirm status
```
enabled
```
.

Pieces Lite data hygiene

Notes stored at

~/.local/share/pieces-lite/pieces_lite.db

. Backup regularly:

cp ~/.local/share/pieces-lite/pieces_lite.db ~/.local/share/pieces-lite/pieces_lite.db.bak

To reset store (if corrupt): stop agents, delete the DB, restart the server (it recreates schema).

Logfire (observability) activation

Log into https://logfire.pydantic.dev/ with project owner account.
Open Settings → Access tokens → Read Tokens.
Click Generate Token, name it
```
codex-read
```
, copy the value.

Add

export LOGFIRE_READ_TOKEN=<token>

~/.codex/mcp.env

; optionally set

LOGFIRE_BASE_URL

if using EU/US specific endpoints.

Edit

~/.codex/config.toml

→

[mcp_servers.logfire]

→

enabled = true

Restart Codex session and run
```
codex mcp list
```
to verify
```
Status: enabled
```
.

Vibe Check setup (meta-review assistant)

Choose provider (OpenAI, Gemini, or OpenRouter) per https://github.com/PV-Bhat/vibe-check-mcp-server.

Export provider key(s) in

~/.codex/mcp.env

(

OPENAI_API_KEY

GEMINI_API_KEY

, or

OPENROUTER_API_KEY

If using hosted Vibe Check, obtain
```
VIBE_CHECK_API_KEY
```
from maintainers and export it.

Un-comment / set

enabled = true

[mcp_servers.vibe_check]

within

config.toml

Optionally limit toolsets via env (
```
VIBE_CHECK_MAX_ITERATIONS
```
, etc.) per README.
Restart Codex and confirm tool availability.

MarkItDown utility server

Enable when bulk converting PDFs/HTML to Markdown.

codex mcp add markitdown -- npx -y markitdown-mcp-npx@latest

(or set

enabled = true

in config block).

No auth required; test with
```
codex mcp get markitdown
```
then invoke
```
convert_file
```
.

5) Reference Matrix (for copy/paste)

~/.codex/config.toml critical entries

[mcp_servers.sequential_thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

[mcp_servers.searxng]
command = "npx"
args = ["-y", "mcp-searxng"]
env = { SEARXNG_URL = "http://localhost:8080" }

[mcp_servers.semgrep]
command = "node"
args = ["/home/work/workspace start/tools/mcp/semgrep/build/index.js"]

[mcp_servers.pieces_lite]
command = "python3"
args = ["/home/work/workspace start/tools/mcp/pieces-lite/pieces_lite_server.py"]

Remember to reload Codex CLI (

codex repl

sessions) after changing

config.toml

mcp.env

so new servers spawn correctly.

6) Change Log (update this section when workflows shift)

2025‑10‑25 — Added Sequential Thinking & SearXNG integration guidance; expanded Semgrep path handling; documented pieces_lite SOP; aligned quick start grid with BMAD checkpoints; added self-host SearXNG instructions.

Model Context Protocol (MCP) — Operational Playbook for BMAD Workstreams

Scope: This guide replaces the older Spec Kit orientation with the current BMAD Method pipeline in
SMS+SQS/
. Every Codex CLI / IDE session shares the global configuration in
~/.codex/config.toml
, so keeping this file accurate guarantees the same toolbelt for all agents. Use it alongside:
SMS+SQS/bmad/core/*
— method definitions & guardrails
SMS+SQS/docs/runbooks/
— per-run acceptance evidence templates
SMS+SQS/docs/mcp-servers/
— deep dives and SOPs (update when workflows move)

1) Quick Decision Grid (BMAD checkpoints)

Server	Primary Capability	BMAD Phase Trigger	Inputs (lowest privilege first)	Outputs / Evidence	Notes
sequential_thinking	Structured reasoning trail & hypothesis revision	Blueprint / Mobilize: task scoping, acceptance planning	Thought payload ( `thought` , `nextThoughtNeeded` , `thoughtNumber` , etc.)	JSON summary of reasoning + stderr box log	No auth; suppress stderr boxes with `DISABLE_THOUGHT_LOGGING=true`
searxng	Multi-engine web search & article extraction	Blueprint / Mobilize: competitive research, standards lookup	Query text, pagination, language, safesearch	SERP JSON, cleaned markdown via `web_url_read`	Self-hosted at `http://localhost:8080` via Docker; swap to a public instance if the local stack is unavailable
semgrep	Local SAST scan & report tooling	Assemble / Deploy: before accepting implementation or PR	Absolute repo path ( `/home/work/workspace start/...` ), config ( `auto` , `p/ci` , etc.)	Findings JSON, rule listings, filtered/exported reports	CLI auto-installs if missing; now supports paths with spaces
chrome_devtools	Live browser, tracing, screenshots	Mobilize / Assemble when UI regression, perf capture, network triage	URL, optional launch args	Traces, screenshots, console logs	Requires local Chrome; mind secrets in browser context
playwright	Deterministic web automation	Mobilize / Assemble smoke paths, headless repro	URL + a11y selectors, origin allowlists	Snapshots, network logs, interactions	Node 20+; set `--allowed-origins` for prod URLs
context7	API/library documentation lookup	Blueprint / Assemble when resolving API drift	Library name or ID	Canonical doc excerpts, URL references	`CONTEXT7_API_KEY` already configured
github	Repo/PR/Issue orchestration	Deploy — branch hygiene, reviews, labels	PAT / OAuth (read-only by default)	File contents, PR status, review actions	Hosted remote; expand privileges only with approval
notion	Knowledge base read/write	Blueprint / Mobilize / Deploy — design sync, decision capture	Notion token, page/db ids	Page content, updates	Keep token least-privilege; follow workspace policy
supabase (disabled)	Read-only DB & docs	On demand for schema validation	Project ref, optional read token	SQL results, schema docs	Enable only when needed; keep read-only
logfire (disabled)	Observability / trace queries	Deploy triage of failing jobs	Logfire read token	Exception listings, trace links	Requires token; currently opt-in
vibe_check (disabled)	Guardrail reviewer	Optional “pattern interrupt” before PR	Provider tokens	Meta-feedback blocks	Enable when high-risk changes loom
pieces_lite	Local note store & recall	Retrospective knowledge reuse	Search query / note content	Stored notes, search hits	Persist lessons under `~/.local/share/pieces-lite`
markitdown (disabled)	Markdown conversion utilities	On demand	Files/blobs	Markdown output	Enable when documentation import needed

2) Global Operating Patterns

BMAD cadence awareness
- Blueprint: gather context (context7, searxng, notion) and codify acceptance via
```
sequentialthinking
```
  .
- Mobilize: attach evidence sources (context7 excerpts, searxng results, notion pages).
- Assemble: run automation (playwright, chrome_devtools) and hardening (semgrep).
- Deploy: coordinate reviews & releases (github, logfire if enabled), then persist outcomes (pieces_lite, notion).
Environment hygiene
All paths in this repo live under
```
/home/work/workspace start
```
. Semgrep’s server now quotes arguments so directories with spaces succeed. Keep environment variables in
```
~/.codex/mcp.env
```
and never hard-code secrets.
Approval policy
Current profile:
```
approval_policy="never"
```
,
```
sandbox_mode="danger-full-access"
```
. You must solve tasks without requesting escalations; remove any temporary tooling before exiting.

3) Per-Server Guidance & SOPs

3.1 Sequential Thinking (

sequentialthinking

) — Enabled

Command:

npx -y @modelcontextprotocol/server-sequential-thinking

(configured).

Tools:
```
sequentialthinking
```
(single tool).
Usage:
1. Kick off during BMAD Blueprint to make acceptance criteria explicit.
2. Increment
```
thoughtNumber
```
  ; update
```
totalThoughts
```
  when adding branches.
3. Capture JSON response and store in the relevant
```
docs/runbooks/*
```
  artifact.
Toggles: export
```
DISABLE_THOUGHT_LOGGING=true
```
to suppress the stderr box art when running in quiet environments.

Manual steps (if re-install required):

Run

npm install -g @modelcontextprotocol/server-sequential-thinking

or rely on NPX.

If offline, mirror the npm tarball (

https://registry.npmjs.org/@modelcontextprotocol/server-sequential-thinking/-/server-sequential-thinking-2025.7.1.tgz

3.2 SearXNG (

searxng_web_search

web_url_read

) — Enabled

Command:

npx -y mcp-searxng

with

SEARXNG_URL=http://localhost:8080

Best moments: confirm standards, gather policy references, competitor scans during Blueprint/Mobilize.
Operational tips:
- Use
```
web_url_read
```
  after
```
searxng_web_search
```
  to extract clean markdown for evidence.
- Keep
```
safesearch
```
  at
```
2
```
  for compliance, set
```
language="all"
```
  unless acceptance requires locale filtering.
Switching instances: if the local instance is unavailable, either restart docker compose or pick another public instance from https://searx.space/ from https://searx.space/ and update
```
~/.codex/config.toml
```
.
Self-host (full engine + browser integration) — cannot be automated here; follow these explicit steps:
1. Install Docker & Docker Compose.
2. ```
git clone https://github.com/searxng/searxng.git
```
  →
```
cd searxng
```
  .
3. Copy
```
searxng.example.yml
```
  to
```
searxng.yml
```
  .
4. Edit
```
searxng.yml
```
  : under
```
engines
```
  , set
```
enabled: true
```
  for every engine you wish to expose; under
```
ui
```
  , set
```
default_theme: simple
```
  .
5. In
```
docker-compose.yml
```
  , ensure
```
networks
```
  allow outbound https for all engines.
6. Launch with
```
docker compose up -d
```
  .
7. Verify at
```
http://localhost:8080
```
  : open the UI, go to Preferences → Engines, enable every engine (scroll to bottom to save).
8. Point Codex config to
```
SEARXNG_URL=http://localhost:8080
```
  .
9. For browser integration (Chrome/Firefox): install the SearXNG search plugin by navigating to
```
http://localhost:8080/opensearch.xml
```
  , click “Add search engine”, then choose it as default in browser settings.
BMAD tie-in: store SERP IDs or extracted markdown under
```
docs/runbooks/
```
for acceptance evidence.

3.3 Semgrep (

scan_directory

, etc.) — Enabled

Command:

node "/home/work/workspace start/tools/mcp/semgrep/build/index.js"

Enhancements made:
- ```
BASE_ALLOWED_PATH
```
  now resolves to
```
/home/work/workspace start
```
  , so full repo scans are accepted.
- Path and config arguments are JSON-quoted to handle spaces safely.

Standard flow:

Run

scan_directory

with

path="/home/work/workspace start/SMS+SQS"

and

config="p/ci"

before marking Assemble complete.

Use
```
export_results
```
to produce SARIF or markdown.
Persist logs under
```
docs/runbooks/task-ledger.md
```
.

Manual reinstall: from
```
tools/mcp/semgrep/
```
, run
```
pnpm install && npm run build
```
. Ensure
```
semgrep
```
CLI on PATH (pip install if absent).
SAST evidence: attach the JSON block from semgrep to BMAD acceptance packages.

3.4 Chrome DevTools & Playwright — Enabled

chrome_devtools
- ```
npx -y chrome-devtools-mcp@latest
```
  (stdio).
- Use for live debugging, capturing traces, verifying network anomalies.
- BMAD: Mobilize (reproduce) and Assemble (perf validation).
- Manual: ensure Chrome ≥ 119 installed; adjust
```
startup_timeout_sec
```
  for slow boot.
playwright
- ```
npx -y @playwright/mcp@latest
```
  .
- Use the
```
browser_*
```
  tools to run deterministic A11y-driven flows.
- Configure allowed origins when targeting staging/prod to respect security.
- BMAD: Mobilize (smoke plan), Assemble (automation evidence).

3.5 Documentation & Knowledge Agents

context7 — Already configured; feed library IDs via
```
codex mcp
```
tools when API drift suspected.
notion — Use to pull or push decisions. Confirm
```
NOTION_TOKEN
```
validity; scope to relevant workspace.
pieces_lite — Local Python server at
```
tools/mcp/pieces-lite/pieces_lite_server.py
```
.
- Tools:
```
pieces_store_note
```
  ,
```
pieces_search_notes
```
  ,
```
pieces_list_recent
```
  .
- BMAD: Deploy / retrospectives; capture gotchas once acceptance closes.
- Storage lives in
```
~/.local/share/pieces-lite
```
  ; do not version control.

3.6 Delivery / Governance

github — Remote HTTP server at
```
https://api.githubcopilot.com/mcp/
```
(read-only). Request additional toolsets only with approval.
supabase (disabled) — Enable when data validation is in scope; ensure
```
read_only=true
```
remains.
logfire (disabled) — For observability deep dives; requires
```
LOGFIRE_READ_TOKEN
```
.
vibe_check (disabled) — Great for complex redesigns; set
```
VIBE_CHECK_API_KEY
```
& provider tokens before enabling.
markitdown (disabled) — Activate for bulk doc conversions.

4) Enabling / Reconfiguring Servers (Human Steps Required)

Use these instructions when infrastructure credentials or GUI interaction is required. Follow exactly; each list is in “autistic detail” to avoid ambiguity.

SearXNG — Full self-host setup with maximum engines

Provision host with Docker & docker-compose (Linux):

sudo apt update && sudo apt install docker.io docker-compose-plugin

```
sudo usermod -aG docker $USER
```
(log out/in).

Fetch sources:

git clone https://github.com/searxng/searxng.git && cd searxng

Configuration file:
- Copy
```
searxng.example.yml
```
  →
```
searxng.yml
```
  .
- Open in editor; under
```
engines
```
  , set
```
enabled: true
```
  for every listed engine.
- Set
```
categories
```
  to include
```
general
```
  ,
```
images
```
  ,
```
news
```
  ,
```
science
```
  , etc., as desired.
- Under
```
outgoing
```
  , configure
```
request_timeout
```
  (e.g., 5s).
Docker compose: run
```
docker compose up -d
```
.
Enable via UI:
- Visit
```
http://localhost:8080
```
  .
- Click the hamburger menu → Preferences → Engines.
- Check “Enable all” (or manually toggle each engine).
- Scroll to the bottom, click Save.
Browser integration:
- In Chrome: visit
```
http://localhost:8080/opensearch.xml
```
  . When prompted, click Add to Chrome → confirm in the omnibox “Manage search engines” panel; set SearXNG as default.
- In Firefox: open the same URL → a banner appears → click Add “SearXNG” → open Settings → Search and select SearXNG as default.

Point Codex: edit

~/.codex/config.toml

to set

SEARXNG_URL="http://localhost:8080"

. Restart Codex CLI/IDE session.

Optional: configure API key restrictions or IP allowlists inside
```
searxng.yml
```
under the
```
server:
```
section if exposed externally.

Notion token rotation

Sign into https://www.notion.so/my-integrations.
Click + New integration → name it
```
SMS+SQS Codex Agent
```
.
Select workspace, set permissions to Read content and Update content.
Copy generated token; update
```
~/.codex/mcp.env
```
(
```
NOTION_TOKEN=...
```
).
In the Notion UI, share required pages/databases with the integration (••• menu → Add connections).

Reload MCP server (

codex mcp remove notion && codex mcp add notion -- npx -y @notionhq/notion-mcp-server@latest

GitHub server scope change (if write access needed)

Generate a PAT at https://github.com/settings/tokens with scopes
```
repo
```
,
```
workflow
```
(minimum).
Export as
```
GITHUB_PAT
```
in
```
~/.codex/mcp.env
```
.

Update

~/.codex/config.toml

if additional toolsets required (

env = { GITHUB_TOOLSETS="repositories,pulls,issues" }

Restart Codex session.

Supabase MCP enablement

Obtain project ref from Supabase dashboard (Settings → General → Project Reference).
For read-only access, create service key with “read-only” permissions.

Update

~/.codex/config.toml

block: set

enabled = true

, add

bearer_token_env_var

Export token into

~/.codex/mcp.env

(e.g.,

export SUPABASE_ACCESS_TOKEN=...

Run
```
codex mcp list
```
to confirm status
```
enabled
```
.

Pieces Lite data hygiene

Notes stored at

~/.local/share/pieces-lite/pieces_lite.db

. Backup regularly:

cp ~/.local/share/pieces-lite/pieces_lite.db ~/.local/share/pieces-lite/pieces_lite.db.bak

To reset store (if corrupt): stop agents, delete the DB, restart the server (it recreates schema).

Logfire (observability) activation

Log into https://logfire.pydantic.dev/ with project owner account.
Open Settings → Access tokens → Read Tokens.
Click Generate Token, name it
```
codex-read
```
, copy the value.

Add

export LOGFIRE_READ_TOKEN=<token>

~/.codex/mcp.env

; optionally set

LOGFIRE_BASE_URL

if using EU/US specific endpoints.

Edit

~/.codex/config.toml

→

[mcp_servers.logfire]

→

enabled = true

Restart Codex session and run
```
codex mcp list
```
to verify
```
Status: enabled
```
.

Vibe Check setup (meta-review assistant)

Choose provider (OpenAI, Gemini, or OpenRouter) per https://github.com/PV-Bhat/vibe-check-mcp-server.

Export provider key(s) in

~/.codex/mcp.env

(

OPENAI_API_KEY

GEMINI_API_KEY

, or

OPENROUTER_API_KEY

If using hosted Vibe Check, obtain
```
VIBE_CHECK_API_KEY
```
from maintainers and export it.

Un-comment / set

enabled = true

[mcp_servers.vibe_check]

within

config.toml

Optionally limit toolsets via env (
```
VIBE_CHECK_MAX_ITERATIONS
```
, etc.) per README.
Restart Codex and confirm tool availability.

MarkItDown utility server

Enable when bulk converting PDFs/HTML to Markdown.

codex mcp add markitdown -- npx -y markitdown-mcp-npx@latest

(or set

enabled = true

in config block).

No auth required; test with
```
codex mcp get markitdown
```
then invoke
```
convert_file
```
.

5) Reference Matrix (for copy/paste)

~/.codex/config.toml critical entries

[mcp_servers.sequential_thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]

[mcp_servers.searxng]
command = "npx"
args = ["-y", "mcp-searxng"]
env = { SEARXNG_URL = "http://localhost:8080" }

[mcp_servers.semgrep]
command = "node"
args = ["/home/work/workspace start/tools/mcp/semgrep/build/index.js"]

[mcp_servers.pieces_lite]
command = "python3"
args = ["/home/work/workspace start/tools/mcp/pieces-lite/pieces_lite_server.py"]

Remember to reload Codex CLI (

codex repl

sessions) after changing

config.toml

mcp.env

so new servers spawn correctly.

6) Change Log (update this section when workflows shift)

2025‑10‑25 — Added Sequential Thinking & SearXNG integration guidance; expanded Semgrep path handling; documented pieces_lite SOP; aligned quick start grid with BMAD checkpoints; added self-host SearXNG instructions.

Model Context Protocol (MCP) — Operational Playbook for BMAD Workstreams

Related Skills

Markdown Converter

Nano Banana Pro

1password