Connect to the MCP Server from Your Code

This page is for people who build their own MCP client or agent. To add the server to an existing app, use the setup for each client instead. There is no sign-in, so there are no OAuth, token or key steps: connect and call.

Connection requirements

Protocol versions

The server speaks five revisions of the MCP specification:

Because the server keeps no session, a client on 2025-11-25 or earlier may send tools/list or tools/call without initialize; the SDKs still start with it to agree on a version.

server/discover answers only under 2026-07-28. Without the _meta envelope it is an unknown method (-32601); with an envelope that lacks io.modelcontextprotocol/clientCapabilities it is refused with -32602 and HTTP 400. Its result describes the server and adds the index the server answers from:

{
  "supportedVersions": ["2026-07-28"],
  "capabilities": {
    "tools": { "listChanged": false },
    "resources": { "listChanged": false, "subscribe": false },
    "prompts": { "listChanged": false },
    "completions": {}
  },
  "_meta": {
    "dev.mindlang/index": {
      "id": "7f889553ec65",
      "built": "2026-10-08",
      "release": "v0.10.2",
      "semantic": true
    },
    "io.modelcontextprotocol/serverInfo": {
      "name": "dev.mindlang/mind",
      "title": "MIND Language",
      "version": "2.0.0"
    }
  },
  "resultType": "complete",
  "ttlMs": 3600000,
  "cacheScope": "public"
}

instructions and the full serverInfo (description, website and icon) are left out above. semantic says that the index holds the data for ranking by meaning; the mode of each search result says how that search was ranked. The same capabilities and server information come back from initialize under 2025-11-25 and earlier.

Server card

The server card describes the server without connecting to it. It is served at https://mcp.mindlang.dev/.well-known/mcp/server-card.json and https://mcp.mindlang.dev/mcp/server-card, as application/mcp-server-card+json with a strong ETag (send If-None-Match for a 304):

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json",
  "name": "dev.mindlang/mind",
  "version": "2.0.0",
  "title": "MIND Language",
  "description": "Search and read MIND language docs, std library signatures and compiler error codes.",
  "websiteUrl": "https://mindlang.dev/docs/mcp",
  "icons": [{ "src": "https://mindlang.dev/favicon.svg", "mimeType": "image/svg+xml", "sizes": ["any"] }],
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp.mindlang.dev/mcp",
      "supportedProtocolVersions": ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"]
    }
  ]
}

The card lists no tools, resources or prompts; ask the server for them with the list methods.

MIND-native form (mic@3)

The server card and the /health route also come as a canonical, flat mic@3 MAP, the encoding of the evidence-chain MAP epilogue that the MIND compiler reads. Send Accept: application/vnd.mind.mic3 (application/mic3 is accepted too). With no Accept, */* or application/json, the answer is the JSON shown above, byte for byte.

• The body is 0x4D, a ULEB128 entry count, then each entry in ascending UTF-8 key order: a ULEB128 key length, the key bytes, a tag and the payload.
• Three tags appear: 0x00 string (ULEB128 length, then UTF-8), 0x01 integer (zigzag ULEB128) and 0x02 bytes (ULEB128 length, then the raw bytes). Booleans are the integers 0 and 1.
• Nested objects and arrays become dotted keys with decimal indices, such as remotes.0.url and remotes.0.supportedProtocolVersions.0.
• Lengths are minimal and there is no padding, so a document has exactly one encoding.

The response carries X-Trace-Hash, the SHA-256 of the body in hex, which browsers can read, and Vary: Accept. application/vnd.mind.mic3 is a vendor media type; no mic@3 media type is registered.

curl -sS -D headers.txt -o card.mic3 -H 'Accept: application/vnd.mind.mic3' \
  https://mcp.mindlang.dev/.well-known/mcp/server-card.json
sha256sum card.mic3
grep -i '^x-trace-hash' headers.txt

Caching

Under 2026-07-28, the results of tools/list, prompts/list, resources/list, resources/templates/list, resources/read and server/discover carry ttlMs: 3600000 and cacheScope: "public": a client may reuse them for an hour. Their content changes only when the server is updated. The HTTP responses from /mcp themselves are Cache-Control: no-store; the server card is public, max-age=3600.

Rate limits and retries

The server allows 600 requests a minute per IP address, and answers more with HTTP 429, Retry-After: 60 and the JSON-RPC error -31429. A burst of a couple of hundred requests within a second or two is refused earlier, at the network edge, before the server sees it: that 429 has a shorter Retry-After and a body that is not JSON-RPC. Honour Retry-After whatever the body looks like, and check the HTTP status before parsing the body as a JSON-RPC response. The rate-limit section shows both answers.

Minimal examples

curl -sS https://mcp.mindlang.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-script","version":"1.0.0"}}}'

curl -sS https://mcp.mindlang.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"explain_error","arguments":{"code":"E2103"}}}'

npm install @modelcontextprotocol/client

import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(new URL("https://mcp.mindlang.dev/mcp")));

const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

const result = await client.callTool({ name: "lookup_symbol", arguments: { name: "string_len" } });
console.log(result.structuredContent);

await client.close();

pip install "mcp>=2.3"

import asyncio

from mcp import Client


async def main():
    async with Client("https://mcp.mindlang.dev/mcp") as client:
        tools = await client.list_tools()
        print([tool.name for tool in tools.tools])

        result = await client.call_tool("lookup_symbol", {"name": "string_len"})
        print(result.structured_content)


asyncio.run(main())

Both examples print the nine tool names, then the string_len match shown on the Tools Reference. With their default settings (tested with @modelcontextprotocol/client 2.3.1 and mcp 2.3.0), the TypeScript client connects with initialize under 2025-11-25 and the Python client under 2026-07-28; both work the same way against this server.

Hosts that start only local servers

A host that can only start local (stdio) servers reaches this server through a small bridge process; the configuration is under Claude Desktop (JSON config) and works for any such host.

Browser clients

A web page can call the server directly. Preflight requests get 204 with:

The page must be served over https://, or over http:// from localhost, 127.0.0.1 or [::1]; see the Origin rules.

Related pages

• Tools Reference: every tool's input and output schema
• Resources and Prompts: URIs, templates and completion
• Limits and Errors: what each error code means
• Security and Privacy: what the server records