MCP Servers

MCP servers connect Ziva to tools from other apps and services. For example, Ziva could read your game’s design notes from a connected service while helping you add a new enemy.

Choose which servers to connect, review their tools, and approve tool calls in chat.

The MCP servers section lets Ziva use tools from other services. To use Ziva’s Godot tools from Claude Code, Codex, or another external AI app, see Ziva as an MCP Server.

Before you connect a server

Get the MCP configuration from the server’s official documentation. A server may also require:

An installed app or runtime, such as Node.js or Python, for servers that run on your computer
An account, API key, or other sign-in details
A URL for a server hosted online

Only connect servers you trust. MCP tools can read or change data according to the access you give them.

Install a bundle

If the server comes as an .mcpb or .zip bundle:

Open Ziva Settings.
Select Models & Providers, then find MCP servers.
Select Install bundle, choose the file, then select Install and connect.

Add a server

Open Ziva Settings.
Select Models & Providers, then find MCP servers.
Select Add manually.
Enter a short, recognizable Name. Ziva uses this name when showing tool calls in chat.
Choose the Server type:
- Local command runs the server on your computer.
- Remote URL connects to a server hosted online.
Ziva fills Config with an example for the type you pick, so you can see which keys that kind of server takes.
Choose where the server is Available in:
- All projects makes it available whenever you use Ziva on this computer.
- This project only keeps it attached to the current Godot project.
Paste the server’s configuration into Config, replacing the example.
Select Test connection. A successful test shows how many tools Ziva discovered.
Select Save and connect.

The settings page shows Connected when the server is ready. Expand its tool count to see the tools it added.

Optional: examples of manual server configuration

Local command example

Some servers provide a command that Ziva starts on your computer. For example, a Context7 configuration looks like this:


{
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"]
}

This example requires Node.js and npx to be installed. Use the exact command and arguments provided by your server.

Remote server example

A hosted server provides a URL and may require authentication headers:


{
  "url": "https://example.com/mcp",
  "headers": {
    "Authorization": "Bearer ${MCP_TOKEN}"
  }
}

Replace the example URL and header with the values from your server. ${MCP_TOKEN} tells Ziva to read the secret from an environment variable instead of storing it in the project configuration.

If a provider gives you a larger configuration containing an mcpServers object, enter the server name in Name and paste only that server’s inner object into Config.

Saved sign-ins are shared across this computer’s projects. They are stored as permission-protected plaintext, not encrypted. Sign out forgets the current saved sign-in on this computer; it does not revoke access at the provider. To revoke access, use the provider’s own account settings.

Many hosted servers ask you to sign in with your account instead of a token. For those, the configuration is just the URL:


{
  "url": "https://example-server.modelcontextprotocol.io/mcp"
}

Select Save and connect, and Ziva opens your browser so you can approve its access to your account. When the browser confirms it succeeded, the row becomes Connected and the server’s tools are available in chat.

If you close the browser without finishing, the row shows Needs sign-in with a Sign in button you can use whenever you are ready.

Signing in requires an https:// address, unless the server runs on your own computer. Ziva refuses to send account credentials over plain http:// to another machine. A server like that can still use a token in headers, but plain HTTP does not encrypt that connection.

Optional: organization sign-in settings and older credentials

Servers that issue you a client ID

Not available in the current plugin release: the issuer setting and clearing credentials preserved from older versions.

Ziva registers itself with most servers automatically. Some organizations disable that and give you a client ID (and sometimes a secret) to use instead. Add it under oauth:


{
  "url": "https://mcp.your-company.example/mcp",
  "oauth": {
    "clientId": "your-client-id",
    "clientSecret": "${COMPANY_MCP_SECRET}",
    "issuer": "https://login.your-company.example/",
    "scope": "mcp:tools"
  }
}

Use your provider’s exact trusted issuer, not its sign-in page. Changing it or the client ID requires signing in again.

Use ${ENV_VAR} for the secret so it stays out of a configuration file you commit. If your organization registered a specific redirect address for Ziva, add it as "redirectUri": "http://127.0.0.1:51122/mcp-oauth/callback". It must be a 127.0.0.1 or localhost address, because Ziva has to receive the sign-in on your own computer. That address is the one Ziva uses by default.

To revoke access, use the provider’s account settings. Sign out in Ziva does not revoke provider access.

Use MCP tools in chat

Once the server is connected, ask Ziva for a task that needs it. You can name the server in your prompt when you want Ziva to use it:


Use context7 to check how to add a collectible coin in Godot. Explain the steps for a beginner.

When a tool needs approval, Ziva shows the server name, tool name, and proposed input:

Allow runs it once.
Always allow lets that server tool run without asking again in this project, including in future chats and after restarts.
Reject prevents the call.

Review the input carefully before approving tools that can edit, publish, delete, or access sensitive data. Ziva does not currently have a screen for managing saved tool approvals. To remove them, reset Ziva’s saved data; this also removes this project’s Ziva chats and settings, so export logs first. Your Ziva sign-in, connected AI accounts, and MCP server sign-ins are kept.

In Plan mode and Ask mode, Ziva only makes MCP tools marked as read-only available. Switch to Default mode when a task needs a tool that changes data.

Manage connected servers

Each server row shows its connection status, scope, tools, and estimated token cost.

Sign in / Sign out manage a hosted server’s account access. See Sign in to a hosted server.
The refresh button reconnects one server and reloads its tools.
Reload config reloads all MCP configuration files.
Disable removes a server’s tools from chat without deleting its setup.
Edit changes its name, scope, or configuration.
The trash button removes it from Ziva.

Tool descriptions count toward the text the model reads on each request. If a server adds many tools, disable it when you do not need it, or limit its tools using the optional settings below.

Optional: choose which server tools Ziva can use


{
  "command": "your-command",
  "args": [],
  "includeTools": ["search_*", "read_*"],
  "excludeTools": ["delete_*"]
}

includeTools keeps only matching tools. excludeTools removes matching tools. The * matches any characters in a tool name. Expand the server’s tool list to find the names to use.

Optional: share server setup with teammates

Servers set to This project only are saved in .ziva/mcp.json inside the project. Share that file with teammates, for example through your team’s version control, to use the same setup.

Do not commit API keys or tokens. Reference secrets with ${ENV_VAR} in env or headers, then have each teammate set that environment variable on their own computer.

If the project already has a .mcp.json file from another MCP-compatible app, Ziva loads its servers automatically. These entries are read-only in Ziva Settings. Edit .mcp.json in your project, then select Reload config to apply changes.

Troubleshooting

The server shows Failed

Select Edit, then Test connection to see the server’s error. Check that:

The configuration is valid JSON
The command, URL, and arguments match the server’s documentation
Any required app or runtime is installed
A local server’s command works on your computer
A hosted server is online and reachable

After fixing the problem, save the server or select its refresh button.

Select Sign in on the server’s row and complete the sign-in in your browser. If it keeps returning to Needs sign-in:

Check that you approved access for the right account.
Select Sign out, then sign in again, to discard credentials the server no longer accepts.
If the server gave you a client ID, check it is spelled correctly and that any ${ENV_VAR} it uses is set on your computer. Ziva lists unset variables on the server’s row.

For servers that use an API key or token rather than a sign-in, check the value in headers or env against the provider’s instructions. If Ziva lists an unset environment variable, set that variable, restart Godot, and test the connection again.

The server connects but its tool is missing

Expand the server’s tool list to see what Ziva discovered.
Check includeTools and excludeTools if you use them.
Leave Plan mode or Ask mode if the missing tool changes data.
Refresh the server after changing its configuration.

Ziva lists tools it cannot currently use as unavailable in the server row.

A project server cannot be edited

Servers loaded from the project’s .mcp.json file are read-only in Ziva Settings. Edit that file directly, then select Reload config.