MCP Server Configuration

Distribute Model Context Protocol (MCP) server configurations with your skill packages.

Overview

MCP (Model Context Protocol) servers extend AI assistants with additional capabilities like database queries, API access, or tool execution. Imprint allows you to distribute MCP server configurations alongside your skills.

Prerequisites

A skill package (either skills-only or code+skills)
An MCP server to distribute (npm package, binary, or script)

Step 1: Create the MCP Directory

In your skill package project:

mkdir mcp

Step 2: Create the Fragment File

Create mcp/YourPackageName.mcp.json:

{
  "servers": {
    "your-server-name": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@your-org/your-mcp-server"]
    }
  }
}

Use your package name as the filename prefix (e.g., MyOrg.Skills.mcp.json) to avoid conflicts.

Step 3: Update Your Project File

Add the MCP fragment to your <Imprint> items:

<ItemGroup>
  <!-- Existing skill files -->
  <Imprint Include="skills\**\*" />
  
  <!-- Add MCP fragments -->
  <Imprint Include="mcp\*.mcp.json" Type="Mcp" />
</ItemGroup>

The Type="Mcp" attribute is required. Without it, the file would be treated as a skill file.

MCP Fragment Format

Basic Structure

{
  "servers": {
    "server-name": {
      "type": "stdio",
      "command": "command-to-run",
      "args": ["arg1", "arg2"]
    }
  }
}

With Environment Variables

{
  "servers": {
    "database-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@myorg/db-mcp-server"],
      "env": {
        "DB_HOST": "${env:DATABASE_HOST}",
        "DB_PORT": "${env:DATABASE_PORT}"
      }
    }
  }
}

With Working Directory

{
  "servers": {
    "local-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./server.js"],
      "cwd": "${workspaceFolder}/tools"
    }
  }
}

Multiple Servers

{
  "servers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@myorg/db-server"]
    },
    "api-client": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@myorg/api-server"]
    },
    "file-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@myorg/file-server"]
    }
  }
}

Server Configuration Properties

Property	Required	Description
`type`	No	Connection type (usually `"stdio"`)
`command`	Yes	The executable to run
`args`	No	Array of command-line arguments
`env`	No	Environment variables
`cwd`	No	Working directory

Common Patterns

npm Package Server

Most MCP servers are distributed as npm packages:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@myorg/my-mcp-server@latest"]
    }
  }
}

The -y flag auto-confirms npx prompts.

Python Server

For Python-based servers:

{
  "servers": {
    "python-server": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "my_mcp_server"]
    }
  }
}

Or with uvx:

{
  "servers": {
    "python-server": {
      "type": "stdio",
      "command": "uvx",
      "args": ["my-mcp-server"]
    }
  }
}

Docker-Based Server

{
  "servers": {
    "docker-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "myorg/mcp-server:latest"]
    }
  }
}

Local Binary

{
  "servers": {
    "local-binary": {
      "type": "stdio",
      "command": "${workspaceFolder}/tools/mcp-server.exe",
      "args": ["--config", "${workspaceFolder}/config.json"]
    }
  }
}

Environment Variables

Reference User Environment

{
  "env": {
    "API_KEY": "${env:MY_API_KEY}"
  }
}

The ${env:VAR_NAME} syntax reads from the user’s environment.

Static Values

{
  "env": {
    "LOG_LEVEL": "debug",
    "VERSION": "1.0.0"
  }
}

Workspace Variables

{
  "env": {
    "PROJECT_ROOT": "${workspaceFolder}"
  }
}

Multiple Packages with MCP

When multiple skill packages provide MCP fragments, all servers are merged:

Package A:

{
  "servers": {
    "database": { ... }
  }
}

Package B:

{
  "servers": {
    "api-client": { ... }
  }
}

Result in mcp.json:

{
  "servers": {
    "database": { ... },
    "api-client": { ... }
  }
}

Server Name Conflicts

If two packages define the same server name, the later one wins. To avoid conflicts:

Prefix server names with your package/org name
Use unique, descriptive names

{
  "servers": {
    "myorg-database": { ... },
    "myorg-api": { ... }
  }
}

Agent-Specific Behavior

Imprint adapts the MCP format for each agent:

VS Code / Copilot

Location: .vscode/mcp.json Root key: servers

{
  "servers": {
    "my-server": { ... }
  }
}

Claude

Location: .claude/mcp.json Root key: mcpServers

{
  "mcpServers": {
    "my-server": { ... }
  }
}

Cursor

Location: .cursor/mcp.json Root key: mcpServers

{
  "mcpServers": {
    "my-server": { ... }
  }
}

Roo Code

Location: .roo/mcp.json Root key: mcpServers

{
  "mcpServers": {
    "my-server": { ... }
  }
}

OpenCode

Location: opencode.json (project root) Root key: mcp

{
  "mcp": {
    "my-server": {
      "type": "local",
      "command": ["npx", "-y", "@your-org/your-mcp-server"],
      "enabled": true
    }
  }
}

You write one fragment with servers, and Imprint handles the translation.

Testing Your MCP Configuration

Step 1: Build Your Package

dotnet build

Step 2: Check the Generated mcp.json

cat .vscode/mcp.json   # Copilot
cat .claude/mcp.json   # Claude
cat .cursor/mcp.json   # Cursor
cat .roo/mcp.json      # Roo Code
cat opencode.json      # OpenCode

Step 3: Verify Server Starts

Test that your server command works:

npx -y @your-org/your-mcp-server

Step 4: Test in AI Assistant

Open your AI assistant and verify it can connect to the server.

Troubleshooting

Server Not Appearing

Check that Type="Mcp" is set on the item
Verify the fragment file is valid JSON
Check the build output for errors

Server Won’t Start

Test the command manually in terminal
Check environment variables are available
Verify the server package is accessible

Merging Issues

Check for server name conflicts
Verify JSON syntax in all fragments
Check .imprint/manifest.json for managed servers

Complete Example

Project Structure

MyOrg.Skills.Database/
├── MyOrg.Skills.Database.csproj
├── skills/
│   └── database/
│       └── SKILL.md
└── mcp/
    └── MyOrg.Skills.Database.mcp.json

Project File

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <IncludeBuildOutput>false</IncludeBuildOutput>
    <DevelopmentDependency>true</DevelopmentDependency>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Zakira.Imprint.Sdk" Version="1.0.0-preview">
      <PrivateAssets>compile</PrivateAssets>
    </PackageReference>
  </ItemGroup>

  <ItemGroup>
    <Imprint Include="skills\**\*" />
    <Imprint Include="mcp\*.mcp.json" Type="Mcp" />
  </ItemGroup>
</Project>

MCP Fragment

{
  "servers": {
    "myorg-database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@myorg/database-mcp-server@^1.0.0"],
      "env": {
        "DB_CONNECTION": "${env:MYORG_DATABASE_CONNECTION}",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Skill File

# Database Skills

This project uses the MyOrg Database MCP server for database operations.

## Available Tools

### query

Execute read-only SQL queries:

Use the database query tool to: SELECT * FROM users WHERE active = true

### execute

Execute write operations (INSERT, UPDATE, DELETE):

Use the database execute tool to insert a new user with email “user@example.com”

## Setup

Ensure the `MYORG_DATABASE_CONNECTION` environment variable is set:

```bash
export MYORG_DATABASE_CONNECTION="Server=localhost;Database=mydb;..."

Best Practices

Always use parameterized queries through the MCP server
Use query for read operations, execute for writes
The server handles connection pooling automatically ```

Next Steps

Consuming Packages - How consumers use your package
Publishing Packages - Publish to NuGet.org
Configuration Reference - All MCP options