Authoring an MCPServer Package

An MCPServer package in Lore is not a server implementation — it is a distribution unit for MCP server configuration. When a developer runs lore pull, the CLI reads the package and writes the MCP server entry into their AI runtime’s config file automatically.

The server itself runs outside of Lore. The Lore package only carries the configuration needed to connect to and configure it. This keeps packages runtime-agnostic.

When to Publish an MCPServer Package

Publish an MCPServer package when you want developers to be able to install and configure your MCP server with a single command:


lore pull my-org/my-mcp-server:1.0.0
# → Writes the MCP server entry into ~/.claude/settings.json, .cursor/mcp.json, etc.

Step 1 — Create the Package Directory


my-mcp-server/
├── manifest.yaml
├── README.md
├── LICENSE
└── content/
    └── en-US.md

Step 2 — Write the manifest.yaml


apiVersion: lore.io/v1
kind: MCPServer
metadata:
  namespace: my-org
  name: my-mcp-server
  version: 1.0.0
spec:
  title: My MCP Server
  description: Provides tools for interacting with the My Service API
content:
  defaultLanguage: en-US
translations:
  - en-US
license: Apache-2.0
tags:
  - api
  - my-service
mcp:
  defaultTransport: stdio
  transports:
    stdio:
      command: npx
      args:
        - -y
        - "@my-org/my-mcp-server"
      env:
        MY_API_KEY: ""           # required — user must set
        LOG_LEVEL: "info"        # optional with default

The mcp: field is the installation descriptor. The CLI uses it to generate the AI runtime configuration entry.

Step 3 — Write the Content File

content/en-US.md should describe what the MCP server provides, its tools, and how to use them. AI harnesses can read this description via lore_get without installing the server.


# My MCP Server
 
Provides tools for interacting with the My Service API from any AI harness.
 
## Available Tools
 
- **`get_item`** — fetches a single item by ID
- **`list_items`** — lists items with optional filters
- **`create_item`** — creates a new item (requires write scope)
 
## Authentication
 
Set `MY_API_KEY` to your My Service API key before use.
Generate one at https://my-service.example.com/settings/api-keys.
 
## Usage Example

get_item(id: “item_abc123”) list_items(status: “active”, limit: 20)

Transport Options

stdio (local process)

The server runs as a local subprocess. Best for servers distributed as npm packages, binaries, or Docker images.


mcp:
  transports:
    stdio:
      command: npx
      args: [-y, "@my-org/my-mcp-server"]
      env:
        MY_API_KEY: ""

After lore pull, the CLI adds to ~/.claude/settings.json:


{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": ["-y", "@my-org/my-mcp-server"],
      "env": { "MY_API_KEY": "" }
    }
  }
}

sse (hosted server)

The server runs remotely. Best for SaaS-hosted MCP servers.


mcp:
  transports:
    sse:
      url: https://mcp.my-service.com/sse
      headers:
        Authorization: "Bearer ${MY_API_KEY}"

Both transports (user choice)


mcp:
  defaultTransport: sse
  transports:
    stdio:
      command: my-mcp-server
      args: ["--port", "3100"]
      env:
        MY_API_KEY: ""
    sse:
      url: https://mcp.my-service.com/sse
      headers:
        Authorization: "Bearer ${MY_API_KEY}"

When both transports are declared, defaultTransport is required. Developers can override with lore pull my-org/my-mcp-server --transport stdio.

Step 4 — Validate


lore validate

The validator checks:

mcp: field is present and well-formed
At least one transport is declared
defaultTransport is set when both transports are present
content/en-US.md exists (default language)

Step 5 — Publish


lore publish

Published versions are immutable. If you change the server’s endpoint, env vars, or command, publish a new version.

Runtime Targets for MCPServer

When a developer runs lore pull, the CLI auto-detects the active AI runtime and writes the config entry to the appropriate file:

Runtime	Config file
Claude Code	`~/.claude/settings.json`
Cursor	`.cursor/mcp.json`
Windsurf	`.windsurfrules` (MCP section)

The developer can override the target with --target:


lore pull my-org/my-mcp-server:1.0.0 --target cursor