Skip to content
  • There are no suggestions because the search field is empty.

MCP server troubleshooting

Applies to
License: MCP Server

Resolve the sign-in, license, file transfer and modeling errors that you see when an AI assistant works with the biGENIUS-X MCP server. Each entry names the symptom, the message the tool returns where there is one, the cause and the fix. The assistant usually shows the message in the chat; ask it for the exact text when it only summarizes it.

Sign-in and license

The bigenius tools are missing or the sign-in fails

Cause: the server is not connected, the sign-in has expired (it is valid for 24 hours), or in the Code tab of the Claude desktop app no session is running yet.
Fix: in the terminal, run /mcp, select bigenius-modeling or bigenius-marketplace and sign in again. In the Code tab, send a first message, open the MCP servers of the session and choose Connect. In other clients, use the sign-in of the server entry described in Connect other AI clients to the MCP server.

A tool reports that the session has expired

Message: The license cannot be checked: the session has expired. Reconnect to sign in again.
Cause: your sign-in is no longer valid.
Fix: connect the server again and sign in, as in the previous entry.

A tool reports that the license does not include the MCP server

Message: The biGENIUS-X license of your organization does not include the MCP server. Contact your biGENIUS-X administrator.
Cause: the organization you signed in with has no MCP Server license. When you belong to several organizations, you may have chosen another one at sign-in.
Fix: open https://mcp.bigenius-x.com/oauth/logout in your browser to end the sign-in session, connect the server again and choose the licensed organization. If no organization of yours has MCP Server, ask your administrator; see Show License plan details.

File transfer

The upload or download command waits for approval

Cause and fix depend on the situation. Delete commands always ask for your approval.

  • Claude changed the command, for example added cd in front of it. The plugin allows only the exact commands that open_workspace and download_changes return. Ask Claude to run the command exactly as returned, as a command of its own.
  • Node.js is missing, so the hooks of the plugin cannot run. Install Node.js, or approve the command when it is a tar and curl command with a mcp.bigenius-x.com URL.
  • Claude Code runs in auto mode, which can refuse the command. Ask Claude to run it again exactly as returned.

The assistant cannot upload the files again

Message: The workspace has changes that are not in the repository yet. Call download_changes and run its command first.
Cause: changes of the tools wait for the download.
Fix: let the assistant run download_changes and its command first.

The workspace has expired

Message: Workspace <workspace ID> does not exist or has expired (2 hours without use). Call open_workspace.
Cause: the server deletes a workspace after 2 hours without use.
Fix: ask the assistant to open the project again. Changes it had already downloaded are in your working tree.

The project files are too large

Message: The inline files exceed 1024 KB. Use a workspace (open_workspace).
Cause: a client without a terminal, such as claude.ai, can pass at most 1 MB of project files with a tool call.
Fix: use Claude Code or another client that runs the upload command.

Message: The project files exceed 100 MB.
Cause: an upload holds at most 100 MB of project files.
Fix: open a ticket with biGENIUS-X support or write to support by e-mail.

Modeling

A model object type is refused

Message: Objects of type <type> cannot be created: the configuration has no active mapping for the type (ui.active), as in the UI. Types of this generator: <types>. or The generator of this project does not offer the type <type>. It offers: <types>.
Cause: your generator does not offer this type, or offers it only for reading from a linked project.
Fix: ask the assistant which model object types your project can create, and plan with those.

The generator configuration is not found

Message: Generator configuration <generator> <version> not found (HTTP 404).
Cause: project.yml names a generator version that biGENIUS-X does not provide, for example a version that is not released.
Fix: check out a branch whose project uses a released generator version, then ask the assistant to open the project again.

A source object or discovery is missing

Cause: the discovery is not in the project yet, or not pulled into your clone. The MCP server reads discoveries only from the discoveries/ folder of your clone and does not connect to source systems.
Fix: add the discovery in the Discovery App and in Data Connections, pull your branch, then ask the assistant to open the project again. See Add a Discovery and Create Source Objects from a Discovery.

An output port cannot be queried

Message: Output port <output port> of <data product> has no active data contract and cannot be queried yet.
Cause: the output port has no data contract with status Active.
Fix: ask the owner of the data product to activate a data contract.

GitHub Copilot reads the YAML files instead of using the tools

Cause: the tools of the server are not selected, the skill is missing, or the chat is not in agent mode.
Fix: in Visual Studio, open Tools in the Copilot chat and select the tools of bigenius-modeling. Check that the skill is at .github/skills/bigenius-x-modeling/SKILL.md; Visual Studio 2026 version 18.5 and later read it. Name the tools in your prompt, for example open_workspace and list_views.

Example

Example: a data engineer belongs to two organizations and signs in with the one without MCP Server. The first tool call returns the license message. They open https://mcp.bigenius-x.com/oauth/logout, run /mcp, select bigenius-modeling, choose the licensed organization on the sign-in page and repeat the question.

Check the result

Ask which layers and model objects the project has. The assistant calls the biGENIUS-X tools without an error and answers with the model objects of your project.

Escalation

When an error remains, open a ticket with biGENIUS-X support, or write to support by e-mail, and include the client and its version, the plugin version (/plugin in Claude Code), the time of the error, the tool name and the exact message. Leave out sign-in tokens and the upload and download URLs: they contain access tokens.

Related articles