---
title: MCP server troubleshooting
description: Resolve the sign-in, license, file transfer and modeling errors that you see when an AI assistant works with the biGENIUS-X MCP server.
---

[Skip to content](https://knowledge.bigenius-x.com/mcp-server-troubleshooting#main-content)

[Contact us](https://knowledge.bigenius-x.com/kb-tickets/new?hsLang=en) [Go to Customer Portal](https://knowledge.bigenius-x.com/customer-portal?hsLang=en)

[![TRI\_Logo\_biGENIUS\_2020\_RGB\_s](https://knowledge.bigenius-x.com/hs-fs/hubfs/Marketing/TRI_Logo_biGENIUS_2020_RGB_s.png?width=150&height=42&name=TRI_Logo_biGENIUS_2020_RGB_s.png)](https://www.bigenius-x.com/)

Open main navigation

Close main navigation

- [Contact us](https://knowledge.bigenius-x.com/kb-tickets/new)
- [Go to Customer Portal](https://knowledge.bigenius-x.com/customer-portal)

 How can we help you?

- There are no suggestions because the search field is empty.

1. [biGENIUS-X Knowledge Base](https://knowledge.bigenius-x.com/?hsLang=en)
2. [Artificial Intelligence](https://knowledge.bigenius-x.com/artificial-intelligence?hsLang=en)
3. [MCP server](https://knowledge.bigenius-x.com/artificial-intelligence?hsLang=en#mcp-server)

# 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](https://knowledge.bigenius-x.com/connect-other-ai-clients-to-the-mcp-server?hsLang=en).

#### 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](https://knowledge.bigenius-x.com/show-licence-plan-details?hsLang=en).

### 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](https://knowledge.bigenius-x.com/add-a-discovery?hsLang=en) and [Create Source Objects from a Discovery](https://knowledge.bigenius-x.com/create-source-objects-from-a-discovery?hsLang=en).

#### 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](https://knowledge.bigenius-x.com/set-up-claude-code-for-bigenius-x?hsLang=en), [Connect other AI clients to the MCP server](https://knowledge.bigenius-x.com/connect-other-ai-clients-to-the-mcp-server?hsLang=en)
- See also: [biGENIUS-X MCP server](https://knowledge.bigenius-x.com/bigenius-x-mcp-server?hsLang=en), [Model a biGENIUS-X project with Claude Code](https://knowledge.bigenius-x.com/model-a-bigenius-x-project-with-claude-code?hsLang=en), [Find data products and write SQL with Claude](https://knowledge.bigenius-x.com/find-data-products-and-write-sql-with-claude?hsLang=en)

- [Getting started](https://knowledge.bigenius-x.com/getting-started?hsLang=en#main-content)

    - [Guidelines](https://knowledge.bigenius-x.com/getting-started?hsLang=en#guidelines)
    - [Start working](https://knowledge.bigenius-x.com/getting-started?hsLang=en#start-working)
    - [Account](https://knowledge.bigenius-x.com/getting-started?hsLang=en#account)
- [General overview](https://knowledge.bigenius-x.com/general-overview?hsLang=en)
- [Artificial Intelligence](https://knowledge.bigenius-x.com/artificial-intelligence?hsLang=en#main-content)

    - [MCP server](https://knowledge.bigenius-x.com/artificial-intelligence?hsLang=en#mcp-server)
- [Application Modules](https://knowledge.bigenius-x.com/application-modules?hsLang=en#main-content)

    - [Administration](https://knowledge.bigenius-x.com/application-modules?hsLang=en#administration)
    - [Solutions](https://knowledge.bigenius-x.com/application-modules?hsLang=en#solutions)
    - [Global Features](https://knowledge.bigenius-x.com/application-modules?hsLang=en#global-features)
    - [Projects](https://knowledge.bigenius-x.com/application-modules?hsLang=en#projects)
    - [Branches](https://knowledge.bigenius-x.com/application-modules?hsLang=en#branches)
    - [Data Connections](https://knowledge.bigenius-x.com/application-modules?hsLang=en#data-connections)
    - [Dataflow Modeling - Overview](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-overview)
    - [Dataflow Modeling - Wizard Steps](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-wizard-steps)
    - [Dataflow Modeling - Terms](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-terms)
    - [Dataflow Modeling - Term Mapping](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-term-mapping)
    - [Dataflow Modeling - Relationships](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-relationships)
    - [Dataflow Modeling - Data Quality](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-data-quality)
    - [Dataflow Modeling - Indexes](https://knowledge.bigenius-x.com/application-modules?hsLang=en#dataflow-modeling-indexes)
    - [Relationship Modeling](https://knowledge.bigenius-x.com/application-modules?hsLang=en#relationship-modeling)
    - [Generate Artifacts](https://knowledge.bigenius-x.com/application-modules?hsLang=en#generate-artifacts)
    - [Project Settings](https://knowledge.bigenius-x.com/application-modules?hsLang=en#project-settings)
    - [Data Marketplace](https://knowledge.bigenius-x.com/application-modules?hsLang=en#data-marketplace)
- [Generators](https://knowledge.bigenius-x.com/generators?hsLang=en#main-content)

    - [Databricks](https://knowledge.bigenius-x.com/generators?hsLang=en#databricks)
    - [Databricks dbt](https://knowledge.bigenius-x.com/generators?hsLang=en#databricks-dbt)
    - [Fabric Lakehouse](https://knowledge.bigenius-x.com/generators?hsLang=en#fabric-lakehouse)
    - [Fabric Warehouse](https://knowledge.bigenius-x.com/generators?hsLang=en#fabric-warehouse)
    - [Microsoft SQL Server](https://knowledge.bigenius-x.com/generators?hsLang=en#microsoft-sql-server)
    - [Oracle](https://knowledge.bigenius-x.com/generators?hsLang=en#oracle)
    - [Snowflake](https://knowledge.bigenius-x.com/generators?hsLang=en#snowflake)
    - [Snowflake dbt](https://knowledge.bigenius-x.com/generators?hsLang=en#snowflake-dbt)
    - [Artifacts](https://knowledge.bigenius-x.com/generators?hsLang=en#artifacts)
    - [Replace Placeholders](https://knowledge.bigenius-x.com/generators?hsLang=en#replace-placeholders)
    - [Target solution environment](https://knowledge.bigenius-x.com/generators?hsLang=en#target-solution-environment)
    - [Deployment](https://knowledge.bigenius-x.com/generators?hsLang=en#deployment)
    - [Deployment with an Azure DevOps pipeline](https://knowledge.bigenius-x.com/generators?hsLang=en#deployment-with-an-azure-devops-pipeline)
    - [Delta Deployment](https://knowledge.bigenius-x.com/generators?hsLang=en#delta-deployment)
    - [Load control environment](https://knowledge.bigenius-x.com/generators?hsLang=en#load-control-environment)
    - [Load data with a native load control](https://knowledge.bigenius-x.com/generators?hsLang=en#load-data-with-a-native-load-control)
    - [Load data with Apache Airflow](https://knowledge.bigenius-x.com/generators?hsLang=en#load-data-with-apache-airflow)
    - [Model Object Type](https://knowledge.bigenius-x.com/generators?hsLang=en#model-object-type)
    - [Properties](https://knowledge.bigenius-x.com/generators?hsLang=en#properties)
    - [Default Terms](https://knowledge.bigenius-x.com/generators?hsLang=en#default-terms)
- [Discovery application](https://knowledge.bigenius-x.com/discovery-application?hsLang=en#main-content)

    - [Discovery configurations](https://knowledge.bigenius-x.com/discovery-application?hsLang=en#discovery-configurations)
- [Best practices](https://knowledge.bigenius-x.com/best-practices?hsLang=en#main-content)

    - [Modeling Approaches](https://knowledge.bigenius-x.com/best-practices?hsLang=en#modeling-approaches)
    - [Use Cases](https://knowledge.bigenius-x.com/best-practices?hsLang=en#use-cases)
    - [Business Rules](https://knowledge.bigenius-x.com/best-practices?hsLang=en#business-rules)
    - [Data Quality Rules](https://knowledge.bigenius-x.com/best-practices?hsLang=en#data-quality-rules)
- [FAQs](https://knowledge.bigenius-x.com/faqs?hsLang=en)
- [Product Release Notes](https://knowledge.bigenius-x.com/product-release-notes?hsLang=en#main-content)

    - [SaaS Application](https://knowledge.bigenius-x.com/product-release-notes?hsLang=en#saas-application)
    - [Discovery application](https://knowledge.bigenius-x.com/product-release-notes?hsLang=en#discovery-application)
    - [Generators](https://knowledge.bigenius-x.com/product-release-notes?hsLang=en#generators)
- [Legal Documents](https://knowledge.bigenius-x.com/legal-documents?hsLang=en#main-content)

    - [Current legal docs](https://knowledge.bigenius-x.com/legal-documents?hsLang=en#current-legal-docs)
    - [Software Product and Limits](https://knowledge.bigenius-x.com/legal-documents?hsLang=en#software-product-and-limits)

- [Contact us](https://knowledge.bigenius-x.com/kb-tickets/new?hsLang=en)
- [Customer Portal](https://knowledge.bigenius-x.com/customer-portal)
- [Sign in](https://knowledge.bigenius-x.com/_hcms/mem/login)

[![biGENIUS logo](https://knowledge.bigenius-x.com/hubfs/TRI_Logo_biGENIUS_2020_RGB-1.svg "biGENIUS logo")](https://www.bigenius-x.com)

<https://www.linkedin.com/company/bigenius> <https://www.youtube.com/@biGENIUS_DWA>

All rights reserved © 2025, biGENIUS AG