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
cdin front of it. The plugin allows only the exact commands thatopen_workspaceanddownload_changesreturn. 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
tarandcurlcommand with amcp.bigenius-x.comURL. - 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
- Previous: Set up Claude Code for biGENIUS-X, Connect other AI clients to the MCP server
- See also: biGENIUS-X MCP server, Model a biGENIUS-X project with Claude Code, Find data products and write SQL with Claude