workiva-mcp

An MCP server for the Workiva platform that pairs API tools with an accumulating knowledge base of confirmed API behaviour — the quirks, dead ends, and undocumented requirements that otherwise cost every agent (and every teammate) the same hour of rediscovery.

The mechanism that makes the pairing matter: failing API calls automatically attach the matching KB entry. An agent that hits 400 "unable to match urn" gets the fix inside the error message itself, without ever knowing the KB exists.

Status: under construction, in small reviewed commits. Roadmap below.

What the KB knows

25 seeded entries, all confirmed against the live API in July 2026: 4 blockers (no API path exists — e.g. connections cannot be created programmatically), 12 gotchas (the obvious approach fails first — e.g. Wdata SQL cannot reference tables by name), and 9 nuances. Entries are dated, version-pinned, and carry the literal error strings they match.

Related MCP server: cocoon

Layout

workiva-mcp/
  src/workiva_mcp/
    server.py     # MCP tools
    kb.py         # KB toolchain: parse, validate, build index, search
    client.py     # Workiva API client: credentials, token refresh, three hosts
    promote.py    # KB drafts -> branch -> PR                           (planned)
  kb/             # the knowledge base: entries/*.md + SCHEMA.md + index.json
  tests/
  .githooks/      # pre-push gate: ruff + pytest + kb check

Development

One-time setup after cloning — activate the pre-push gate:

git config core.hooksPath .githooks

Every push then runs ruff, the tests, and the KB check first (git push --no-verify bypasses in an emergency).

uv run workiva-mcp                        # boots the stdio server
uv run pytest                             # tests
uv run ruff check .                       # lint
uv run python -m workiva_mcp.kb check     # validate entries + index currency
uv run python -m workiva_mcp.kb build     # rebuild kb/index.json after editing entries

kb/index.json is generated — never edit it by hand; edit kb/entries/*.md and rebuild.

Register with Claude Code from a clone:

claude mcp add workiva -- uv run --directory <path-to-clone> workiva-mcp

Credentials

# ~/.workiva/credentials        (chmod 600)
[settings]
default_profile = sandbox

[default]
client_id = ...
client_secret = ...

[sandbox]
client_id = ...
client_secret = ...
# optional per-profile endpoint overrides:
# token_url / platform_base / wdata_base / chains_base

The file is re-read at call time, so edits — rotating a secret, switching default_profile — take effect on the next call without restarting the server. Profile precedence: explicit argument > WORKIVA_PROFILE > [settings] default_profile > [default]. With no file at all, WORKIVA_CLIENT_ID / WORKIVA_CLIENT_SECRET serve the default profile. WORKIVA_CREDENTIALS_FILE overrides the file location.

Write safety

The server is read-only by default: tools marked WRITE (create table, upload/import, connection refresh, …) refuse with an explanatory message and touch nothing. Enable writes with WORKIVA_ALLOW_WRITES=1 in the server's environment, or allow_writes = true under [settings] in ~/.workiva/credentials — the file is re-read at call time, so flipping it takes effect immediately, and an explicit env value (even 0) always wins. Read-only means no user-visible workspace mutations: wdata_run_sql's internal temp-query mechanics stay allowed.

Capturing new knowledge

kb_add writes drafts to ~/.workiva/kb/drafts/ (override with WORKIVA_KB_DRAFTS) — local, instant, no review, never part of the package. Search reads bundled entries and your drafts, so a quirk you hit today helps you again tomorrow, before any review happens. Drafts carry confidence: reported and pass the same schema linter as real entries.

Promotion into the shared KB is a deliberate human act:

uv run workiva-kb list                      # what's waiting locally
uv run workiva-kb promote <draft-id> ...    # re-stamp as confirmed, branch, commit, open PR

(--no-pr for branch+commit only, --keep-drafts to leave local copies, --confidence to override the confirmed re-stamp.) Workspace-specific findings simply never get promoted.

Roadmap

• Scaffold: package, entry point, empty stdio server

• KB data vendored: 25 entries, schema, CC-BY-4.0 license

• KB toolchain: parse + validate + index build + weighted search, tests, pre-push gate

• KB tools: kb_search / kb_list / kb_get, KB packaged into the wheel

• Local drafts overlay + kb_add

• Workiva client foundation: credential profiles in ~/.workiva/credentials, token lifecycle, three-host transport

• Auto-hint mechanism + read-only Wdata tools

• SQL execution, saved queries, connections listing

• Write gate (WORKIVA_ALLOW_WRITES / allow_writes) + modifying Wdata tools: create table, upload → import → poll, connection refresh

• Graph + Spreadsheets tools (writes gated)

• Escape hatch (platform / wdata / chains)

• promote CLI: drafts → PR (workiva-kb)

• NOTICE, v0.1.0 tag, uvx install

License

Code: Apache-2.0 (see LICENSE). KB entries under kb/, once landed: CC-BY-4.0.