Fusion Mcp

Fusion MCP Setup Guide

When to use

Use this skill when a user asks:

• what Fusion MCP is
• what it can do
• how to install/configure it
• how to verify that it is working
• how to troubleshoot a failing Fusion MCP setup

Typical triggers:

• "what is fusion mcp"
• "help me set up fusion mcp"
• "how do I use fusion mcp with copilot"

When not to use

Do not use this skill for:

• implementing product features unrelated to MCP setup
• making destructive environment changes without user confirmation
• assuming private repository details that are not visible

Required inputs

Collect before proposing setup steps:

• user environment (OS, shell, editor/runtime)
• target client where MCP will run (for example VS Code MCP config or terminal)
• whether the user wants released image (GHCR) or local build from source
• transport mode (stdio for editor client config or HTTP endpoint for local checks)
• whether required access is ready (Docker, GitHub auth for GHCR, API keys)

If details are missing, ask concise follow-up questions first.

Instructions

1. Explain what this MCP server provides:

• Fusion-oriented MCP capabilities for retrieval and workflow support
• tool surface may evolve over time as the server is a PoC
• examples today may include retrieval, index guidance, metadata summaries, and skill discovery

2. Use the official README quick start as source of truth, then present a minimal 2-step setup path:

• choose image source: GHCR release image or local build
• configure VS Code MCP using Docker stdio only (scope for this iteration)

3. For GHCR image setup, include auth prerequisites before pull/run:

• gh auth login -h github.com -w
• gh auth refresh -h github.com -s read:packages
• gh auth token | docker login ghcr.io -u <github-username> --password-stdin

4. For local build setup, use the documented sequence so the API is built, started, and validated:

• cp .env.example .env
• docker compose up -d --build api
• then follow the health-check step in references/local-http-quickstart.md to confirm the API is healthy

5. Provide required configuration categories without exposing secret values:

• Azure Search keys (AzureSearch__*)
• Foundry keys/settings (Foundry__*)
• optional runtime vars (ASPNETCORE_ENVIRONMENT, HOST_PORT)

6. Provide a lightweight MCP smell test:

• run initialize and confirm a successful response
• run tools/list and confirm at least one tool is returned
• run one non-destructive tools/call against an available tool
• pass criteria: call response is non-empty (content or structuredContent contains data)
• note: do not hard-code a fixed tool list; tool inventory can change between versions

7. Troubleshoot in documented order:

• GHCR unauthorized/403 -> refresh GH auth and Docker login
• Apple Silicon manifest mismatch -> add Docker arg --platform linux/amd64
• tools/list returns empty or basic query fails -> re-check API key env mapping and MCP server selection in VS Code
• startup looks healthy but tool behavior is partial -> re-check env/config/auth alignment and restart MCP server

8. When MCP setup fails, MCP behavior is incorrect, or the user asks to file a bug, produce a bug report draft from assets/bug-report-template.md.

• default target repository: equinor/fusion-poc-mcp
• include concrete repro steps, expected vs actual behavior, and troubleshooting already attempted
• include non-sensitive environment details (OS, VS Code version, Docker version, image tag, transport mode)
• never include secrets, API keys, or raw token values

9. For uncertainty or repo-private constraints, state assumptions explicitly and link to authoritative docs instead of guessing.

Expected output

Return:

• short explanation of Fusion MCP and when to use it
• setup path tailored to the user environment (GHCR/local, stdio/HTTP)
• minimal validation checklist with concrete pass criteria
• troubleshooting steps mapped to observed error symptoms
• bug report draft (when setup fails/misbehaves or user requests) using assets/bug-report-template.md with default target equinor/fusion-poc-mcp
• script snippets when user asks for copy/paste automation aids
• assumptions and missing information called out explicitly
• links to the exact upstream docs used

References

• references/README.md
• assets/bug-report-template.md

Safety & constraints

Never:

• request or expose secrets, tokens, or credentials
• invent setup commands that are not supported by project documentation
• claim setup succeeded without validation output
• run destructive commands without explicit user confirmation

Always:

• prefer official repository documentation as source of truth
• provide least-privilege, minimal-change setup guidance first
• separate confirmed facts from assumptions
• keep guidance scoped to VS Code + Docker for this iteration

Summary

Briefly describe what failed and impact to workflow.

Environment

• OS:
• VS Code version:
• Docker version:
• MCP transport mode (for example stdio):
• MCP image/build used (tag or local):

Preconditions

• Which prerequisites were completed
• Which credentials/config categories were configured (do not include secret values)

Steps to reproduce

1. 2. 3.

Expected behavior

What should happen.

Actual behavior

What happened instead.

Validation evidence

• initialize result:
• tools/list result:
• basic non-destructive tools/call result:

Troubleshooting already attempted

- -

Logs / output (sanitized)

Add relevant sanitized snippets only. Remove keys, tokens, and sensitive values.

Additional notes

-

Changelog

0.1.1 - 2026-03-05

patch

• #55 `2d346c8` - Add required ownership metadata (metadata.owner, metadata.status) to all skills. Owner is set to @equinor/fusion-core (repository default) and status is set according to skill lifecycle (active for production skills, experimental for early-stage skills). Sponsor metadata was considered but is not required for MVP.

resolves equinor/fusion-core-tasks#474

0.1.0 - 2026-03-02

minor

• #30 `1ad69fb` - Add an experimental fusion-mcp skill scoped to VS Code + Docker setup, with prerequisite guidance, MCP client configuration instructions, actionable troubleshooting, and MCP JSON-RPC validation examples including a non-empty basic query pass check.

Bug-report guidance and template updates are tracked in a dedicated follow-up changeset.

resolves equinor/fusion-core-tasks#409

patch

• #30 `1ad69fb` - Add bug report guidance and template usage for MCP setup failures/misbehavior, including default issue-target guidance in the skill and sanitized report structure.

resolves equinor/fusion-core-tasks#413

Local build + HTTP endpoint quickstart (Fusion MCP)

Use this reference when the user wants to run fusion-poc-mcp locally and validate its HTTP health and MCP readiness.

Prerequisites

• Docker Desktop (or Docker Engine + Compose)
• Required configuration values available for:
• AzureSearch__*
• Foundry__*

Do not request users to paste secrets into chat.

Quick setup

1. Copy env template:

cp .env.example .env

2. Populate required env values in .env.

3. Start the API:

docker compose up -d --build api

4. Verify service health:

curl -sS http://localhost:${HOST_PORT:-8080}/health

5. Run baseline smoke validation:

bash scripts/demo.sh smoke

Expected MCP outcome

A healthy setup should return a non-empty tool list and support at least one successful non-destructive MCP tools/call.

Examples of tools often seen today include search_index, search_indexes_describe, search_metadata_types, and skills, but this list can evolve.

For skills-focused verification:

bash scripts/mcp-skills-smoke-check.sh

Common fixes

• Health check fails: verify .env values and restart with docker compose up -d --build api.
• Tools missing or partial behavior: verify Azure Search/Foundry env names and key availability.
• Port conflict: set HOST_PORT in .env to a free port and retry.

Related references

• VS Code MCP config example: vscode-mcp-config.md

Sources

• https://github.com/equinor/fusion-poc-mcp/blob/main/README.md
• https://github.com/equinor/fusion-poc-mcp/blob/main/contribute/setup.md
• https://github.com/equinor/fusion-poc-mcp/blob/main/contribute/configuration.md
• https://github.com/equinor/fusion-poc-mcp/blob/main/contribute/testing.md

MCP JSON-RPC payload snippets

Use these snippets when users need direct MCP requests without local helper scripts.

Each example includes:

• short purpose
• request payload JSON
• expected return shape

initialize

Initialize an MCP session and receive capabilities/instructions.

{
	"jsonrpc": "2.0",
	"id": 1,
	"method": "initialize",
	"params": {
		"protocolVersion": "2024-11-05",
		"clientInfo": {
			"name": "fusion-mcp-snippets",
			"version": "0.0.0-dev"
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"protocolVersion": "2024-11-05",
		"capabilities": { "tools": {} },
		"instructions": "..."
	}
}

tools/list

List all available MCP tools exposed by the server.

{
	"jsonrpc": "2.0",
	"id": 2,
	"method": "tools/list",
	"params": {}
}

{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"tools": [
			{ "name": "search_index" },
			{ "name": "search_indexes_describe" },
			{ "name": "search_metadata_types" },
			{ "name": "skills" }
		]
	}
}

tools/call → search_indexes_describe

Get configured indexes and basic routing guidance.

{
	"jsonrpc": "2.0",
	"id": 3,
	"method": "tools/call",
	"params": {
		"name": "search_indexes_describe",
		"arguments": {
			"includeMarkdown": false
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 3,
	"result": {
		"content": [
			{ "type": "text", "text": "..." }
		],
		"structuredContent": {
			"indexes": [
				{ "name": "fusion-docs" },
				{ "name": "fusion-framework" }
			]
		}
	}
}

tools/call → search_index

Run retrieval against a target Fusion index.

{
	"jsonrpc": "2.0",
	"id": 4,
	"method": "tools/call",
	"params": {
		"name": "search_index",
		"arguments": {
			"index": "fusion-framework",
			"query": "service discovery",
			"top": 5
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 4,
	"result": {
		"content": [
			{ "type": "text", "text": "..." }
		],
		"structuredContent": {
			"index": "fusion-framework",
			"query": "service discovery",
			"result": []
		}
	}
}

tools/call → search_metadata_types

Summarize metadata-type distribution for a query.

{
	"jsonrpc": "2.0",
	"id": 5,
	"method": "tools/call",
	"params": {
		"name": "search_metadata_types",
		"arguments": {
			"index": "fusion-docs",
			"query": "*",
			"top": 20
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 5,
	"result": {
		"content": [
			{ "type": "text", "text": "..." }
		],
		"structuredContent": {
			"metadataTypes": [
				{ "type": "markdown", "count": 20 }
			]
		}
	}
}

tools/call → skills

Get skill recommendations and lifecycle advisory guidance.

{
	"jsonrpc": "2.0",
	"id": 6,
	"method": "tools/call",
	"params": {
		"name": "skills",
		"arguments": {
			"query": "is there a fusion skill for helping me write issues",
			"top": 5
		}
	}
}

{
	"jsonrpc": "2.0",
	"id": 6,
	"result": {
		"content": [
			{ "type": "text", "text": "..." }
		],
		"structuredContent": {
			"intent": "research",
			"primarySkill": { "name": "..." },
			"advisory": { "mode": "instructions-only" }
		}
	}
}

Fusion MCP references

Use this folder for concrete setup playbooks that support fusion-mcp.

Current iteration scope: VS Code MCP client configuration with Docker stdio transport and local HTTP endpoint validation quickstart.

Choose the right guide

• vscode-mcp-config.md
• Use when the user needs VS Code MCP client configuration with Docker stdio.
• Includes GHCR auth, config template, validation checks, and troubleshooting.

• local-http-quickstart.md
• Use when the user wants to build/run locally and verify via HTTP endpoint.
• Includes local compose flow, health checks, smoke checks, and common fixes.

• mcp-call-snippets.md
• Use when the user asks for copy/paste MCP JSON-RPC payload examples.
• Includes request payloads and expected response shapes.

Source of truth

• Upstream repo: https://github.com/equinor/fusion-poc-mcp
• Upstream README: https://github.com/equinor/fusion-poc-mcp/blob/main/README.md
• Upstream contribute docs: https://github.com/equinor/fusion-poc-mcp/tree/main/contribute

VS Code MCP config quick reference (Fusion MCP)

This guide is a distilled setup reference based on the upstream Fusion MCP README. Use it when the user asks for a concrete VS Code MCP config example.

Prerequisites

• Docker available locally
• Access to image source:
• GHCR release image (ghcr.io/equinor/fusion-poc-mcp[:tag]), or
• locally built image (fusion-poc-mcp:local). From the repository root, you can build and tag this image with:

    docker build -t fusion-poc-mcp:local .

• Required API keys available to the user (do not request values in plain text)

If using GHCR image, authenticate first:

gh auth login -h github.com -w
gh auth refresh -h github.com -s read:packages
gh auth token | docker login ghcr.io -u <github-username> --password-stdin

Minimal VS Code MCP config (Docker stdio)

Use this as a baseline template and adapt env values as needed.

{
  "servers": {
    "fusion-poc-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--read-only",
        "--tmpfs", "/tmp:rw,size=64m",
        "--cap-drop=ALL",
        "--security-opt=no-new-privileges",

        "-e", "MCP_TRANSPORT=stdio",
        "-e", "FusionSkills__CloneDirectory=/tmp/fusion-skills",
        "-e", "FusionSkills__SqlitePath=/tmp/fusion-skills-index.db",

        "-e", "AzureSearch__fusion-framework__ApiKey=${input:azure-framework-key}",
        "-e", "AzureSearch__fusion-docs__ApiKey=${input:azure-docs-key}",
        "-e", "Foundry__ApiKey=${input:foundry-key}",

        "ghcr.io/equinor/fusion-poc-mcp:v1"
      ]
    }
  },
  "inputs": [
    {
      "id": "azure-framework-key",
      "type": "promptString",
      "description": "Azure Search API key for fusion-framework index",
      "password": true
    },
    {
      "id": "azure-docs-key",
      "type": "promptString",
      "description": "Azure Search API key for fusion-docs index",
      "password": true
    },
    {
      "id": "foundry-key",
      "type": "promptString",
      "description": "Foundry API key",
      "password": true
    }
  ]
}

Platform/runtime notes

• Apple Silicon with amd64-only image: add Docker arg "--platform", "linux/amd64".
• If you need persistent /tmp state for skills DB/cache, replace --tmpfs /tmp... with a Docker volume mount.
• Prefer pinned release tags (:v1, :v1.2.3) over :latest for predictable behavior.

Verification checklist

Use this lightweight smell test instead of a fixed tool-name check:

• Run initialize and confirm successful handshake.
• Run tools/list and confirm at least one tool is returned.
• Pick one non-destructive tool from the returned list and run tools/call.
• Pass criteria: response is non-empty (content or structuredContent contains data).
• Fail criteria: empty tool list or empty/failed tool response; treat as setup failure and apply troubleshooting below.

Examples of tools often seen today include search_index, search_indexes_describe, search_metadata_types, and skills, but this set can evolve.

If running locally for quick validation, use upstream smoke checks:

bash scripts/demo.sh smoke
bash scripts/mcp-skills-smoke-check.sh

Troubleshooting quick map

• 403 / unauthorized pulling image: refresh GH auth + Docker login to GHCR.
• no matching manifest for linux/arm64/v8: add --platform linux/amd64.
• Tools missing in client: re-check env variable names and API-key availability.

Sources

• https://github.com/equinor/fusion-poc-mcp/blob/main/README.md
• https://github.com/equinor/fusion-poc-mcp/blob/main/contribute/setup.md
• https://github.com/equinor/fusion-poc-mcp/blob/main/contribute/configuration.md
• https://github.com/equinor/fusion-poc-mcp/blob/main/contribute/testing.md