Here are two scenarios for using the FusionAuth API MCP Server, which is an MCP server that connects over STDIO and can be used to configure a FusionAuth instance.

Local development — letting an agent configure FusionAuth and recording the steps for later automation Production read-only — using an agent to safely query a production instance

⚠ Preview Warning: The FusionAuth MCP server is a preview release and may break, change, or be discontinued. It is intended for development and test instances. Never give an MCP client unrestricted access to a production instance.

Prerequisites A running FusionAuth instance (local or remote) Node.js installed An MCP-compatible client (e.g., Claude Desktop) Scenario 1: Local Development

This lets you configure FusionAuth and record steps to apply to other instances.

Create a read-write API key. In your local FusionAuth instance, create an API key with the permissions you need. For full configuration work, you may want broad permissions, but always follow the principle of least privilege — for example, if you're only working with applications and themes, grant only those permissions. Configure your MCP client. For Claude Desktop on macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json to add the FusionAuth MCP server. Since you want full configuration access, omit the USE_TOOLS restriction (note: you'll need a model that can handle ~200k tokens): { "mcpServers": { "fusionauth-mcp-api": { "command": "npx", "args": [ "@fusionauth/mcp-api" ], "env": { "API_KEY_APIKEYAUTH": "<your-read-write-api-key>", "API_BASE_URL": "http://localhost:9011" } } } }

Restart Claude Desktop after saving.

Verify the connection. Open Claude Desktop and ask:

"Which tools do you have access to?"

You should see a list of all FusionAuth API tools (300+).

Configure FusionAuth using natural language. Now you can describe what you want in plain English. For example:

"Set up a custom registration form for the Pied Piper application. Require email address and password, but allow first name and favorite color to be optional. Put them all on one page."

Or:

"Add a user with an email address of test@example.com and a password of password."

The agent will make the appropriate API calls on your behalf.

Export your configuration for automation. Once you've configured things the way you want, ask the agent to export the configuration so you can turn it into repeatable scripts:

"Please export the configuration for the Pied Piper application to a kickstart file."

"Export the current tenant configuration as a Terraform file."

This gives you a reproducible artifact you can commit to source control or use in CI/CD pipelines.

You can reduce tool scope. If you only need to work with specific operations (e.g., no deletes), you can reduce the tool list to improve performance and limit risk:

"env": { "API_KEY_APIKEYAUTH": "<your-api-key>", "API_BASE_URL": "http://localhost:9011", "USE_TOOLS": "create,update,retrieve,search,other" }

This omits the delete APIs and reduces the tool list by ~20%.

Scenario 2: Production Read-Only Queries with an Agent

The security model of this approach consists of three layers: the instance you connect to, the tool categories you expose, and the permissions on the API key itself. Combining a read-only API key with USE_TOOLS="retrieve,search" gives you defense in depth for production queries.

Create a read-only API key. In your production FusionAuth instance, create an API key scoped to read-only operations only. This is the most important security step — the API key defines the ceiling of what the agent can do. Configure your MCP client with read-only tools. Edit your MCP client config to point at your production instance and restrict tools to retrieve and search only: { "mcpServers": { "fusionauth-mcp-api-prod": { "command": "npx", "args": [ "@fusionauth/mcp-api" ], "env": { "API_KEY_APIKEYAUTH": "<your-read-only-api-key>", "API_BASE_URL": "https://your-production-fusionauth-instance.com", "USE_TOOLS": "retrieve,search" } } } }

Setting USE_TOOLS="retrieve,search" reduces the tool list by 66% and ensures the agent cannot create, update, patch, or delete anything. This is a second layer of defense.

Verify read-only access. Ask the agent:

"Which tools do you have access to?"

Confirm that only retrieve and search tools are listed — no create, update, delete, or patch tools should appear.

Query production data. You can now safely ask questions like:

"Is PKCE enforced for all my applications?" "How many users do I have in my FusionAuth instance?" "How many FusionAuth applications do I have?"

The agent will use the read-only API tools to answer your questions without modifying anything.

@nikola Have you checked out our kickstarts or APIs? You should be able to apply the license keys and configure your environments as needed.

If this isn't what you mean, please just give me a little more detail on what you are trying to do and I'll help the best I can.

@anthea-mo It looks like the fix is to upgrade.

I also found this on the users accounts being locked.

If this information does not get you where you need, please let me know.

If you're unsure whether the hosted service validates immediately, I'd open a support ticket first since they'll be able to confirm the exact behavior for your version.

Note that as of release 1.68.0 (released in late Jun 2026), there is a mfa_deleter role that can remove MFA from a user.

Please see the release notes for more details.

Since we can’t store API keys in code,

FYI, with the release of 1.64.0, you now can store secrets elsewhere and have lambdas retrieve them.

See the documentation for more details.

My understanding is that state is a map of parameters passed into the template context by FusionAuth, not something you explicitly define in the template itself. If that snippet works even though you can't find a local declaration, it's likely being injected by the email rendering process. Have you checked the template variable documentation or tried outputting the contents of state to see which keys are actually available at runtime?