Fusion Mcp

Fusion MCP Setup Guide

When to use

Use when a user asks:

• what Fusion MCP is
• what it can do
• how to install/configure it
• how to verify 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

• Implementing product features unrelated to MCP setup
• Making destructive environment changes without user confirmation
• Assuming private repository details not visible
• Answering source-backed questions about Fusion Framework APIs, EDS components, or the skill catalog — once MCP is running, use fusion-research for that

Required inputs

Collect before proposing setup steps:

• user environment (OS, editor/runtime)
• target client where MCP will run (VS Code is primary target)
• whether user's Equinor Entra account is available

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
• hosted as a managed service — no local infrastructure required for most developers
• retrieval tools: search, search_framework, search_docs, search_eds, search_indexes, search_backend_code
• tool surface may evolve over time

2. Guide user to set up the hosted production server — the only recommended path:

• no Docker, no API keys, no local clone needed
• VS Code authenticates via Microsoft Entra (Equinor account)
• use the one-click install link for prod (see references/vscode-mcp-config.md)
• or manual config with "type": "http" and server URL (see references/vscode-mcp-config.md)
• don't suggest local Docker, GHCR, or self-hosted alternatives unless user has explicit operational need

3. Describe the authentication flow:

• on first tool invocation VS Code prompts sign in with Equinor Entra account
• tokens managed automatically; silent renewal when possible, interactive prompt when needed
• access controlled by existing Fusion role assignments

4. Provide a lightweight MCP smell test:

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

5. Troubleshoot in documented order:

• Entra sign-in prompt not appearing → verify oauth.clientId in config and that VS Code is signed in with an Equinor account
• 401 Unauthorized → re-authenticate via VS Code account settings; ensure Equinor Entra account is active
• tools/list returns empty or tool call fails → verify MCP server entry is selected/enabled in VS Code and retry after reloading
• partial tool behavior → check VS Code Output > Copilot for error details and restart the MCP server

7. When MCP setup fails or user asks to file a bug, produce a bug report draft from assets/bug-report-template.md.

• default target repository: equinor/fusion-mcp
• include concrete repro steps, expected vs actual behavior, and troubleshooting already attempted
• include non-sensitive environment details (OS, VS Code version, MCP server URL, Entra account type)
• never include secrets, tokens, or raw credential values

8. 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
• hosted prod setup steps tailored to the user environment
• validation checklist: run initialize (expect success response), run tools/list (expect at least one tool), run one tools/call (expect non-empty content or structuredContent)
• 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-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
• guide users to the hosted production server; do not suggest local Docker or self-hosted alternatives
• provide least-privilege, minimal-change setup guidance first
• separate confirmed facts from assumptions

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

1.0.1 - 2026-05-07

patch

• #170 `5e43223` - Apply caveman-compress prose style to SKILL.md and references.

• Drop articles, filler, hedging from SKILL.md activation body
• Compress mcp-call-snippets and vscode-mcp-config references

• #168 `6c56986` - Fix diagnostic issues in fusion-mcp SKILL.md

• Resolve contradiction between "only recommended path" and exception clause for self-hosted alternatives
• Replace ambiguous "minimal validation checklist" with explicit three-step validation criteria
• Restructure troubleshooting from flat bullets into numbered Check/Fix substeps to reduce cognitive load
• Add coverage for users without an Equinor Entra account

1.0.0 - 2026-05-04

major

• #150 `7f7c2d4` - Update skill to reflect the new equinor/fusion-mcp server

• Replace all references to the old fusion-poc-mcp PoC server and image
• Promote the hosted production server (https://mcp.api.fusion.equinor.com/mcp) as the only recommended setup path; remove local Docker/GHCR guidance for end users
• Update VS Code config to use HTTP + OAuth (Microsoft Entra) instead of Docker stdio with API keys
• Rewrite references/vscode-mcp-config.md with one-click install link and manual OAuth config template
• Update tool inventory to match the new server: search, search_framework, search_docs, search_backend_code, search_eds, search_indexes
• Rewrite references/mcp-call-snippets.md with accurate per-tool parameter tables sourced from server code
• Remove references/local-http-quickstart.md (local setup not promoted to end users)
• Update troubleshooting to cover hosted-server failure modes (Entra auth, 401, empty tool list)

Resolves equinor/fusion-skills#149

0.1.3 - 2026-04-22

patch

• #143 `3c02e1d` Thanks @alftore! - Document backend code tools in the Fusion MCP setup guide.

• Add search_backend_code to retrieval tool examples
• Add get_backend_symbol and list_backend_projects in the available backend tooling list

0.1.2 - 2026-03-21

patch

• #107 `d75d8c6` - Document search_skills in the MCP server tool surface.

• add explicit tool listing to the setup instructions: search_framework, search_docs, search_eds, search_skills, search_indexes, skills, skills_index_status

Resolves equinor/fusion-core-tasks#834

• #106 `1f8a01d` - Connect fusion-mcp to fusion-research as a next-step redirect.

• add "When not to use" entry directing source-backed research questions to fusion-research once MCP is running

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

MCP JSON-RPC payload snippets

Direct MCP request snippets for verifying/exploring the Fusion MCP server (https://mcp.api.fusion.equinor.com/mcp).

Note: In VS Code, tool invocations are handled automatically. Raw JSON-RPC is useful for direct debugging or scripted smoke tests.

>

Auth: OAuth bearer token required; 401 without valid token. Use authenticated client (VS Code REST Client with Entra token, or curl with Authorization: Bearer <token>) — or VS Code where auth is automatic.

---

Tool inventory

---

initialize

Initialize session, receive capabilities.

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

Expected response shape:

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

---

tools/list

List all available MCP tools.

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

Expected response shape:

{
	"jsonrpc": "2.0",
	"id": 2,
	"result": {
		"tools": [
			{ "name": "search" },
			{ "name": "search_framework" },
			{ "name": "search_docs" },
			{ "name": "search_backend_code" },
			{ "name": "search_eds" },
			{ "name": "search_indexes" }
		]
	}
}

---

tools/call → search

Generic search against any configured index. Use when you know the exact index. Prefer index-specific tools (search_framework, search_docs, etc.) for most cases.

Required: index, query

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

Expected response shape:

{
	"jsonrpc": "2.0",
	"id": 3,
	"result": {
		"content": [{ "type": "text", "text": "..." }],
		"structuredContent": {
			"index": "fusion-framework",
			"query": "service discovery",
			"top": 5,
			"result": [
				{
					"pageContent": "...",
					"metadata": { "type": "tsdoc", "pkg_name": "..." }
				}
			]
		}
	}
}

---

tools/call → search_framework

Search the Fusion Framework index. Covers TypeScript source (TSDoc), markdown docs, Storybook stories, and cookbooks from equinor/fusion-framework. Supports promoted field filters.

Required: query

{
	"jsonrpc": "2.0",
	"id": 4,
	"method": "tools/call",
	"params": {
		"name": "search_framework",
		"arguments": {
			"query": "how to register a service",
			"pkg_name": "@equinor/fusion-framework-react",
			"type": "tsdoc",
			"top": 5
		}
	}
}

---

tools/call → search_docs

Search Fusion platform documentation. Covers platform guidance, ADRs, blog posts, and incident reports.

Required: query

{
	"jsonrpc": "2.0",
	"id": 5,
	"method": "tools/call",
	"params": {
		"name": "search_docs",
		"arguments": {
			"query": "authentication flow for Fusion apps",
			"tags": ["docs"],
			"top": 5
		}
	}
}

---

tools/call → search_backend_code

Search .NET/C# source from Fusion backend services. Filters: repository, service/project, declaration kind, namespace.

Required: query

{
	"jsonrpc": "2.0",
	"id": 6,
	"method": "tools/call",
	"params": {
		"name": "search_backend_code",
		"arguments": {
			"query": "IPersonService",
			"declarationKind": "interface",
			"top": 5
		}
	}
}

---

tools/call → search_eds

Search the Equinor Design System (EDS) index. Covers component docs, props, usage examples, and accessibility guidance.

Required: query

{
	"jsonrpc": "2.0",
	"id": 7,
	"method": "tools/call",
	"params": {
		"name": "search_eds",
		"arguments": {
			"query": "Button component accessibility",
			"top": 5
		}
	}
}

---

tools/call → search_indexes

Discover configured indexes and get routing guidance.

Returns metadata for all configured indexes, including descriptions and optional markdown guide content. Use this to understand which index to target for a given query.

No required parameters.

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

Expected response shape:

{
	"jsonrpc": "2.0",
	"id": 8,
	"result": {
		"content": [{ "type": "text", "text": "..." }],
		"structuredContent": {
			"total": 4,
			"indexes": [
				{
					"name": "fusion-framework",
					"description": "...",
					"guideCount": 1
				},
				{
					"name": "fusion-docs",
					"description": "...",
					"guideCount": 1
				},
				{
					"name": "eds",
					"description": "...",
					"guideCount": 1
				},
				{
					"name": "backend-code",
					"description": "...",
					"guideCount": 1
				}
			]
		}
	}
}

Fusion MCP references

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

Choose the right guide

• vscode-mcp-config.md
• Use when the user needs VS Code MCP client configuration.
• Covers the hosted production server with OAuth (Microsoft Entra) sign-in.
• Includes one-click install link, manual config template, auth flow, and troubleshooting.

• 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-mcp
• Upstream README: https://github.com/equinor/fusion-mcp/blob/main/README.md
• Upstream docs: https://github.com/equinor/fusion-mcp/tree/main/docs

VS Code MCP config quick reference (Fusion MCP)

Distilled setup reference based on the upstream Fusion MCP README.

Prerequisites

• An Equinor Microsoft Entra account (your regular Equinor login)
• VS Code with GitHub Copilot

No Docker, no API keys, no local clone required.

One-click install (recommended)

Click the link below to add Fusion MCP to your VS Code configuration:

[Install Fusion MCP (Prod)](vscode:mcp/install?%7B%22name%22%3A%22fusion-mcp%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.api.fusion.equinor.com%2Fmcp%22%7D)

Manual setup

Open the VS Code Command Palette and run MCP: Open User Configuration, then add:

{
  "servers": {
    "fusion-mcp": {
      "type": "http",
      "url": "https://mcp.api.fusion.equinor.com/mcp"
    }
  }
}

Authentication flow

1. First tool invocation: VS Code detects authentication required 2. VS Code prompts sign-in with Equinor Microsoft Entra account 3. After sign-in, tokens managed automatically — silent renewal when possible, interactive prompt when needed 4. Access controlled by your existing Fusion role assignments

Verification checklist

• Run initialize and confirm a successful response.
• 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.

Troubleshooting quick map

• Sign-in prompt not appearing: verify the fusion-mcp server entry is enabled in VS Code MCP settings and that you are signed in with an Equinor account.
• 401 Unauthorized: re-authenticate via VS Code account settings; ensure your Equinor Entra account is active.
• tools/list returns empty: verify the fusion-mcp server entry is enabled in VS Code MCP settings and reload the MCP server.
• Partial tool behavior: check VS Code Output > Copilot for error details and restart the MCP server.

Sources

• https://github.com/equinor/fusion-mcp/blob/main/README.md