Skip to main content

MCP Server

The public FormKiQ MCP Server lets an MCP client discover selected FormKiQ operations and call a deployed API. This guide targets server v0.2.0. Its release version and bundled OpenAPI version are independent of the backend and SDK versions.

Install and configure​

You need Python 3.11+, Git, pipx, a deployed FormKiQ JWT endpoint, and a current Cognito AccessToken with the intended site permissions. Use the stack's HttpApiUrl; this release sends bearer JWTs and does not add IAM signing or API-key authentication merely by changing the endpoint.

Configure your MCP client to launch:

{
"command": "pipx",
"args": ["run", "--spec", "git+https://github.com/formkiq/formkiq-mcp-server.git@v0.2.0", "formkiq-mcp-server"],
"env": {
"MCP_TRANSPORT": "stdio",
"FORMKIQ_API_ENDPOINT_URL": "https://example.execute-api.us-east-2.amazonaws.com",
"FORMKIQ_JWT": "REPLACE_WITH_ACCESS_TOKEN",
"FORMKIQ_API_GROUPS": "core"
}
}

Adapt the wrapper to your client's configuration format. Supply the JWT through protected local configuration or the host's secret mechanism; never commit a real value. The repository README contains client-specific examples.

For a checkout-based installation, pin a release, run uv sync --locked, then uv run --locked python server.py. Its .env loading is limited to the current working directory; exported environment values take precedence. Restart after changing the JWT. Token refresh is manual in this release.

Discover before invoking​

The default configuration is read-only. Use list_formkiq_operations to inspect enabled operations and describe_operation for the focused request schema. The OpenAPI resource is openapi://formkiq/jwt. API groups, module declarations, write/purge flags, and caller policies filter tool availability; discovery does not grant backend permissions.

For example, the get_document tool accepts:

{"documentId":"example-document-id","siteId":"default"}

The response retains operationId, method, statusCode, ok, and body. Treat non-2xx statuses as failures; transport, JSON, binary-response, timeout, and bounded-response errors are also surfaced as tool errors. A processing response is not automatically polled until completion.

Add capabilities deliberately​

SettingEffect
FORMKIQ_API_GROUPSSelects the supported API groups offered by the server.
FORMKIQ_MODULESDeclares installed capabilities for filtering; it does not install or license a module.
FORMKIQ_ENABLE_WRITES=trueEnables supported mutation tools. Backend permissions still apply.
FORMKIQ_ENABLE_PURGE=trueSeparately opts into permanent purge in conjunction with writes.

Start with the default read-only mode and the smallest site grants. Review your MCP client's approval behavior before enabling mutations. A document or tool result can contain untrusted instructions; it must not decide whether deletion or external disclosure is authorized.

For local HTTP testing, the server supports Streamable HTTP at http://localhost:8000/mcp. Keep development HTTP on the intended local boundary. Follow the repository's caller authentication and deployment configuration before exposing it remotely; the backend JWT alone is not authentication for every caller of a shared MCP service.

Compatibility and troubleshooting​

Use the release's bundled OpenAPI snapshot unless you deliberately supply a compatible, pinned override. An override or module declaration cannot add missing backend endpoints. Check the endpoint mode, current AccessToken, siteId, tool filters, and backend permissions when discovery or calls fail.

See the MCP application tutorial, versions and compatibility, and public release README.