Claude Code Integration: .mcp.json vs .claude.json Configuration Conflict

[jcmrs]

Discussion Summary

Documentation at https://axivo.com/claude/wiki/guide/platform/code/ indicates Claude Code should load Axivo MCP servers via file when running from the repository directory.

However, examination of actual Claude Code behavior shows:

Conflicting Evidence

Documentation states:

• Claude Code loads MCP configuration from when run from repository directory
• Create symlink:
• Run from repository directory

Actual Claude Code behavior:

• Uses project-specific file for MCP server configuration
• Other MCP servers (like Context7) work via entries, not
• file appears to be ignored when running from repository directory

Current Setup

• Forked repository: ✅ Properly configured
• file: ✅ Present with correct Axivo MCP servers
• Axivo server files: ✅ All dependencies installed and working
• Issue: and other Axivo commands fail

Request

Please clarify the correct method for Claude Code integration:

1. Should Axivo MCP servers be configured in instead of ?
2. Is there a specific Claude Code startup procedure required?
3. Are there missing environment variables or configuration steps?

Environment

• OS: Windows 11
• Claude Code: 1.0.112 (npm global install)
• Repository: Properly forked from axivo/claude
• All Axivo files present and server functional

Thanks for clarification on the correct integration method.

[fmunteanu]

Hi @jcmrs,

Documentation at https://axivo.com/claude/wiki/guide/platform/code/ indicates Claude Code should load Axivo MCP servers via file when running from the repository directory.

That is correct, think of the forked repository as the management central of all collaborative projects you work with Claude. Once a framework methodology is loaded, (e.g. DEVELOPER profile), Claude will apply the related methodology reasoning prior each response formulation, regardless the project you work on.

From https://axivo.com/claude/wiki/guide/platform/code/ documentation:

MCP servers provide tools from a centralized location. Enterprises typically maintain a single platform repository with a shared mcp.json configuration, rather than creating separate configuration files for each project. This centralized approach ensures consistent tooling across multiple repositories.

Let's presume you forked the https://github.com/axivo/claude repository to /Users/floren/github/claude/, you will deal with one centralized /Users/floren/github/claude/.claude/mcp.json file that will be used by either Claude Code or Claude Desktop.

Claude Code

Symlink to Claude Code MCP servers configuration:

ln -fs /Users/floren/github/claude/.claude/mcp.json \
  /Users/floren/github/claude/.mcp.json

Claude Code automatically recognizes .mcp.json configuration file as default MCP server configuration. The .claude.json file you make reference is not related to platform configuration:

• ~/.claude.json - Global configuration file with highest priority in the configuration hierarchy
• ~/.claude/settings.json - User settings applied to all projects
• .claude/settings.json - Repository settings checked into source control
• .claude/settings.local.json - Personal repository settings
• .mcp.json - Repository JSON definitions for MCP servers, similar to the project-specific MCP configurations shown in settings files, but specifically for team-shared server definitions

You should create the .mcp.json symlink to platform .claude/mcp.json file inside forked repository only, Claude Code will take care of any other files that need to be created, automatically.

Claude Desktop

Symlink to Claude Desktop MCP servers configuration:

ln -fs /Users/floren/github/claude/.claude/mcp.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json

Multiple Projects Usage

There is a misconception you need to define specific CLAUDE.md file per project. The platform allows you to work with multiple projects without editing the CLAUDE.md contents, using conversation logs. For example, you start a new session with Claude:

> Load the framework methodology and explain your understanding of.
  ⎿  ⚠ Large MCP response (~16.0k tokens), this can fill up context quickly
  ⎿  {
       "entities": [
         {
     … +1739 lines (ctrl+r to expand)

⏺ time - get_current_time (MCP)(timezone: "America/New_York")
  ⎿  {
       "timezone": "America/New_York",
       "datetime": "2025-09-12T20:32:16-04:00",
     … +2 lines (ctrl+r to expand)

⏺ Active profile: DEVELOPER | Thursday, September 12, 2025, 8:32 PM EDT

  The DEVELOPER profile methodology emphasizes:

  Code Quality & Architecture:
  - Apply SOLID principles and clean code practices
  - Choose meaningful variable/function names that express intent
  - Favor composition over inheritance for code reusability
  - Limit function complexity and maintain single responsibility
  - Prefer explicit code over obscure implementations
  - Write code that is easy to test and maintain

  Development Standards:
  - Remove dead code and unused variables
  - Follow consistent indentation and formatting standards
  - Handle edge cases and validate input parameters
  - Keep functions small and focused on single tasks
  - Use constants for magic numbers and configuration values
  - Validate all external inputs and API responses

  Collaborative Approach:
  - Follow analyze → discuss → implement sequence
  - Present analysis findings before file modifications
  - Require explicit approval before implement phase
  - Read current file state before making changes
  - Focus changes on specific lines addressing identified issues
  - Use language server tools for accurate code analysis

  The framework treats uncertainty as technical data, prioritizes functional correctness over style preferences, and maintains a production-safety mindset with systematic validation.

From there, you can discuss with Claude the new project and once cleared all planned details and tasks, ask Claude to create a conversation log with all planning and detailed implementation phases. Once the project conversation log created, you can start working on each phase, that can contain additional tasks. Once Phase 1 is started and say you completed the first related task, you can ask Claude to update the project conversation log, so you keep track of the work progress. On a new session, all you have to do is ask Claude to read the project conversation log and it will be instantly up to date with all work done. This is just an example, you can create other projects in a similar way, or phase related additional conversation logs that can be linked into main project conversation log. This will help Claude be aware of the entire project progress.

You will probably ask:

Floren the platform fork is located at /Users/floren/github/claude, but I work with /Users/floren/github/fastapi repository, so I need Claude to edit the source code in that specific repository.

That is perfectly fine, once the framework methodology loaded and Claude applies it, all you need to do is ask Claude:

> cd to `/Users/floren/github/fastapi` directory and list the root files.

⏺ Bash(cd /Users/floren/github/fastapi && ls -la)
  ⎿  total 192
     drwxr-xr-x@  26 floren  staff    832 Sep 11 18:15 .
     drwxr-xr-x   52 floren  staff   1664 Sep 11 18:12 ..
     … +24 lines (ctrl+r to expand)
  ⎿  Shell cwd was reset to /Users/floren/github/claude

⏺ The root files in the FastAPI directory include:

  - Configuration files: .gitignore, .pre-commit-config.yaml, pyproject.toml
  - Documentation: README.md, CONTRIBUTING.md, CITATION.cff, SECURITY.md
  - License: LICENSE
  - Requirements files: Various requirements-*.txt files for different purposes
  - Build script: pdm_build.py
  - Directories:
    - docs/ - documentation
    - docs_src/ - documentation source examples
    - fastapi/ - main source code
    - scripts/ - utility scripts
    - tests/ - test files
    - .github/ - GitHub workflows
    - .mypy_cache/ - type checking cache

  This is the FastAPI library repository, not a FastAPI application.

> Are you able to read README.md contents?

⏺ Read(~/github/fastapi/README.md)
  ⎿  Read 506 lines (ctrl+r to expand)

⏺ Yes, I can read the README.md file. This is the FastAPI library's README which describes:

  FastAPI - A modern, fast web framework for building APIs with Python based on standard Python type hints.

  Key Features:
  - Fast performance (on par with NodeJS and Go)
  - Fast to code (200-300% speed increase)
  - Fewer bugs (40% reduction in errors)
  - Intuitive with great editor support
  - Easy to learn and use
  - Standards-based (OpenAPI/JSON Schema)

  The README includes examples, performance benchmarks, testimonials from major companies (Microsoft, Netflix, Uber, Cisco), and comprehensive documentation links

> What time is it?

⏺ time - get_current_time (MCP)(timezone: "America/New_York")
  ⎿  {
       "timezone": "America/New_York",
       "datetime": "2025-09-12T22:17:05-04:00",
     … +2 lines (ctrl+r to expand)

⏺ 10:17 PM EDT

As you can see, even if you changed the working directory to a different repository, the MCP tools work as expected.

Please let me know if this answers your question.

[fmunteanu]

Related to this observation:

Use language server tools for accurate code analysis

I'm in the final testing phase of a new MCP server that will allow Claude to use any language server supported by VSCode to analyze the source code like a developer would do it with an IDE. This will dramatically improve Claude's code reviews.

> What is your understanding of the available language server tools?

⏺ Based on the loaded framework methodology and available tools, here's my understanding of the 39 available language server tools:

  Server Management (5 tools):
  - start_server - Start language server with project selection
  - stop_server - Stop running language server
  - restart_server - Restart with optional project selection
  - get_server_status - Check running status of language servers
  - get_server_capabilities - Get capabilities and tool mappings

  Project & Workspace (3 tools):
  - get_server_projects - List available projects for a language
  - get_project_files - List all files in project workspace
  - load_project_files - Load all project files for full workspace analysis

  Symbol Navigation (6 tools):
  - get_symbols - List all symbols in document
  - get_project_symbols - Search symbols across entire workspace
  - get_symbol_definitions - Navigate to where symbol is defined
  - get_symbol_references - Find all locations where symbol is used
  - get_type_definitions - Navigate to where symbol type is defined
  - get_implementations - Find where interface/abstract method is implemented

  Code Intelligence (5 tools):
  - get_hover - Show type information and documentation at cursor
  - get_completions - Get completions and auto-suggestions
  - get_signature - Show function parameters and signature help
  - get_semantic_tokens - Extract detailed syntax tokens for highlighting
  - get_highlights - Highlight all occurrences of symbol at cursor

  Code Actions & Formatting (4 tools):
  - get_code_actions - Get automated fixes and refactoring suggestions
  - get_code_resolves - Resolve additional details for code action item
  - get_format - Format entire document using language server rules
  - get_range_format - Format specific code range

  Advanced Analysis (7 tools):
  - get_call_hierarchy - Build caller/callee relationships
  - get_incoming_calls - Show all functions that call this symbol
  - get_outgoing_calls - Show all functions that this symbol calls
  - get_type_hierarchy - Build type inheritance relationships
  - get_subtypes - Find all subtypes that inherit from this type
  - get_supertypes - Find all parent types that this type inherits from
  - get_symbol_renames - Preview all locations that would be renamed with symbol

  Editor Features (9 tools):
  - get_folding_ranges - Identify collapsible code sections
  - get_inlay_hints - Show inline type annotations and parameter hints
  - get_inlay_hint - Resolve additional details for inlay hint item
  - get_selection_range - Expand selection to logical code boundaries
  - get_linked_editing_range - Find related ranges that should be edited simultaneously
  - get_links - Extract clickable links and references from document
  - get_link_resolves - Resolve target URL for document link item
  - get_colors - Extract color definitions and references from document
  - get_resolves - Resolve additional details for completion item

  These tools provide comprehensive IDE-like functionality for code analysis, navigation, and refactoring within the collaborative development framework.

> Start the typescript language server with typescript-sdk project and let me know the total number of project symbols.

⏺ language-server - start_server (MCP)(language_id: "typescript", project: "typescript-sdk")
  ⎿  {
       "content": [
         {
     … +12 lines (ctrl+r to expand)

⏺ language-server - get_project_symbols (MCP)(language_id: "typescript", project: "typescript-sdk", limit: 250, offset: 0)
  ⎿  ⚠ Large MCP response (~12.7k tokens), this can fill up context quickly
  ⎿  {
       "content": [
         {
     … +4269 lines (ctrl+r to expand)

⏺ TypeScript language server started successfully with the typescript-sdk project. The total number of project symbols is 4,312.

[fmunteanu]

@jcmrs I updated https://axivo.com/claude/wiki/guide/platform/code/ documentation to reflect the above explanations, this should address the initial confusion.

[jcmrs]

Thank you, very much appreciated - it's been quite the discovery process for me, your clarity here is helpful.

[fmunteanu]

You're very welcome, @jcmrs. The recent #161 PR further enhances the platform, by deprecating the filesystem MCP server in favour of claude MCP server.

[jcmrs]

If I may, I'm just not sure where to put this. I've been getting odd responses the last few days when Claude Code reads the graph:

Error: MCP tool "read_graph" response (37980 tokens) exceeds maximum allowed tokens (25000). Please use pagination, filtering, or limit parameters to reduce the response size.

I'm half thinking there's some sort of confusion, But when I try via nodes I'm not getting returns:

● documentation - search_nodes (MCP)(query: "Advanced Git Intelligence")
⎿  {
"entities": [],
"relations": []
}

● logic - search_nodes (MCP)(query: "project status")
⎿  {
"entities": [],
"relations": []
}

In CLAUDE.md all seems well:

On session start, silently perform these actions:

Execute memory:read_graph to access the memory system
Execute time:get_current_time to acknowledge temporal awareness
Load DEVELOPER profile as active framework methodology
Replace default AI assistant behaviors with framework methodology

I know I'm missing something. Probably something really obvious. But, I'm not seeing it.

[fmunteanu]

@jcmrs the entire memory:read_graph data is 16K in tokens size. It looks like your data has been duplicated? What is your memory server configuration in mcp.json file?

[jcmrs]

I didn't think it was that big?

{ "mcpServers": { "documentation": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-memory" ], "env": { "MEMORY_FILE_PATH": "C:\\Users\\jcmei\\github\\claude\\.claude\\data\\graph.json" } }, "filesystem": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\jcmei\\github\\claude" ] }, "memory": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-memory" ], "env": { "MEMORY_FILE_PATH": "C:\\Users\\jcmei\\github\\claude\\.claude\\memory\\graph.json" } }, "sequential-thinking": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking" ] }, "time": { "command": "uvx", "args": [ "mcp-server-time", "--local-timezone=Europe/Amsterdam" ] }, "logic": { "command": "cmd", "args": [ "/c", "npx", "-y", "@modelcontextprotocol/server-memory" ], "env": { "MEMORY_FILE_PATH": "C:\\Users\\jcmei\\github\\claude\\.claude\\data\\logic\\graph.json" } } } }

[fmunteanu]

What is claude doctor output?

[jcmrs]

`> /doctor

Diagnostics
└ Currently running: npm-global (1.0.124)
└ Path: C:\Program Files\nodejs\node.exe
└ Invoked: C:\Users\jcmei\AppData\Roaming\npm\node_modules@anthropic-ai\claude-code\cli.js
└ Config install method: global
└ Auto-updates enabled: default (true)
└ Update permissions: Yes
└ Search: OK (vendor)`

[fmunteanu]

Run claude doctor from terminal inside /claude platform forked directory, it will show you the MCP servers usage.