# mcp-server-card

## What is MCP Server Card?

**MCP Server Card** is a JSON manifest at `/.well-known/mcp/server-card.json` that describes your MCP server: name, version, transport, and capabilities. It lets AI agents automatically discover an MCP server by domain without any manual setup.

**MCP (Model Context Protocol)** is Anthropic's open protocol for standardizing how AI agents interact with tools and data. An agent "connects" to a server and receives a set of tools, resources, and prompts.

Analogy: if your API is a shop, the MCP Server Card is the sign showing opening hours and what's on offer.

## Why do you need MCP Server Card?

Before MCP discovery was standardized, every integration required manual setup: a developer would hand-configure the URL and describe the tools. At scale, with many agents and servers, this doesn't work.

MCP Server Card solves the **federated tool discovery** problem:

- **Automatic configuration** — an agent checks `/.well-known/mcp/server-card.json` and immediately sees available tools
- **Versioning** — the client verifies protocol version and compatibility
- **Security** — the card describes authentication requirements (OAuth, API key)

Especially useful for: SaaS with an API, DevTools, enterprise knowledge bases, and any service designed for AI agents.

## How do you implement MCP Server Card?

**Minimal card:**

```json
{
  "serverInfo": {
    "name": "My Service MCP",
    "version": "1.0.0"
  },
  "transport": {
    "type": "http",
    "endpoint": "https://api.example.com/mcp"
  },
  "capabilities": {
    "tools": true,
    "resources": false,
    "prompts": false
  }
}
```

**Extended variant with authentication:**

```json
{
  "serverInfo": {
    "name": "Example CRM MCP Server",
    "version": "1.2.0",
    "description": "CRM data and workflow automation via MCP",
    "contact": {
      "email": "mcp@example.com",
      "url": "https://example.com/mcp-docs"
    }
  },
  "transport": {
    "type": "http",
    "endpoint": "https://api.example.com/mcp/v1",
    "protocol": "MCP/1.0"
  },
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": true
  },
  "authentication": {
    "required": true,
    "methods": ["oauth2", "api-key"],
    "oauthEndpoint": "https://auth.example.com/.well-known/openid-configuration"
  },
  "rateLimit": {
    "requestsPerMinute": 60,
    "headerName": "RateLimit-Remaining"
  }
}
```

**Publishing in Astro:**

```typescript
// src/pages/.well-known/mcp/server-card.json.ts
export async function GET() {
  const card = {
    serverInfo: { name: 'My MCP', version: '1.0.0' },
    transport: { type: 'http', endpoint: 'https://example.com/api/mcp' },
    capabilities: { tools: true }
  };
  return new Response(JSON.stringify(card), {
    headers: { 'Content-Type': 'application/json' }
  });
}
```

**For Nginx (static file):**

```nginx
location = /.well-known/mcp/server-card.json {
    alias /var/www/well-known/mcp-server-card.json;
    add_header Content-Type application/json;
    add_header Access-Control-Allow-Origin *;
}
```

## How do we check MCP Server Card?

The scanner checks three paths in order of priority:
1. `/.well-known/mcp/server-card.json`
2. `/.well-known/mcp/server-cards.json`
3. `/.well-known/mcp.json`

For each path the scanner verifies:

1. **HTTP status** — if none returned 200 → **fail**
2. **Valid JSON** — body parses without errors
3. **Required fields** — `serverInfo.name` and `serverInfo.version` are present
4. **Transport** — `transport.type` and `transport.endpoint` are present
5. **Capabilities** — the `capabilities` object is present

**pass** — at least one path returned HTTP 200 with valid JSON and all required fields. **fail** — all paths are unreachable or the JSON is invalid.

[← All glossary terms](/en/glossary)