Skip to Content
DocsMCP Servers
DocsMCP Servers

MCP Servers

Model Context Protocol (MCP) servers give Ziva extra tools it can use while helping with your game. Depending on the server, those tools might be web search, framework documentation, work with your studio’s issue tracker, read design data from another service, or run a specialized workflow.

You keep control: choose which servers are available, review their tools, and approve tool calls from the 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.

Add a server

  1. Open Ziva Settings.

  2. Select Integrations, then find MCP servers.

  3. Select Add server.

  4. Enter a short, recognizable Name. Ziva uses this name when showing tool calls in chat.

  5. 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.

  6. 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.

  7. Paste the server’s configuration into Config, replacing the example.

  8. Select Test connection. A successful test shows how many tools Ziva discovered.

  9. Select Save and connect.

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

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.

Sign in to a hosted server

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.

Ziva opens your browser only in response to something you just did — saving a server that needs a sign-in, or selecting Sign in. Starting Godot never opens sign-in pages on its own, however many servers are waiting for one.

A few things worth knowing:

  • Ziva remembers the sign-in on this computer, for every project, so you do not repeat it each time you open Godot. It refreshes access in the background as it expires.
  • Sign out on the server row forgets those credentials. Use it when you switch accounts, or when you want to remove Ziva’s access from that computer.
  • If you revoke Ziva’s access from the server’s own settings, its row returns to Needs sign-in.
  • 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 be used with a token in headers.

Servers that issue you a client ID

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}",
    "scope": "mcp:tools"
  }
}

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.

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 the latest API documentation before updating this script.

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

  • Accept runs it once.
  • Allow always lets that server tool run without asking again 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 your other settings, sign-in, and stored API keys.

In Plan mode, Ziva only makes MCP tools marked as read-only available. Switch out of Plan 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.
  • Refresh 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 take up context on every request. If a server adds many tools, disable it when you do not need it or limit the tools it exposes:

{
  "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.

Share a server with your project

Servers set to This project only are saved in .ziva/mcp.json inside the project. You can commit that file so teammates receive 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.

The server shows Needs sign-in

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 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.

Last updated on
Local ProvidersZiva as an MCP Server