MCP Server Guide

Operation pages as Markdown

Any operation detail URL under /groups/…/specs/…/…/operations/… can be fetched as Markdown instead of HTML. Send Accept: text/markdown or Accept: text/plain (optionally with quality values) on the same GET request; the response body is a Markdown document and Content-Type is text/markdown or text/plain depending on which wins in negotiation. HTML responses include a Link header (rel="alternate", type="text/markdown") pointing at the same URL so clients can discover the alternate representation.

Automated agents and IDE tools should prefer Markdown for operation reference material when parsing documentation, and HTML when a rendered page is required.

Connection details

MCP endpoint: {baseUrl}/mcp (current environment: https://swaggeroni-test.myeci.net/api/mcp)

OAuth discovery endpoint: {baseUrl}/.well-known/oauth-protected-resource (current environment: https://swaggeroni-test.myeci.net/api/.well-known/oauth-protected-resource)

For authenticated access, configure either an API key header or an OAuth2 access token header in your MCP server entry. If authentication is required and no valid credentials are sent, the server responds with a 401 plus WWW-Authenticate details so clients can prompt for sign-in.

mcp.json examples

Use the same server configuration format in Cursor and VS Code. Save this as .cursor/mcp.json (project or user) or .vscode/mcp.json (workspace).

Basic (when anonymous access is enabled)

{
  "servers": {
    "swaggeroni": {
      "url": "https://swaggeroni-test.myeci.net/api/mcp",
      "type": "http"
    }
  }
}

Authenticated with API Key

{
  "servers": {
    "swaggeroni": {
      "url": "https://swaggeroni-test.myeci.net/api/mcp",
      "type": "http",
      "headers": {
        "x-api-key": "<api-key>"
      }
    }
  }
}

Authenticated with OAuth2

{
  "servers": {
    "swaggeroni": {
      "url": "https://swaggeroni-test.myeci.net/api/mcp",
      "type": "http"
    }
  }
}

OAuth2 authorization code flow

When using OAuth2 authorization code flow, keep mcp.json limited to the MCP server URL and transport type, and let your MCP client perform sign-in and token refresh.

For this flow, do not hardcode API keys or static Authorization values in mcp.json.

What to do

1. Set the server URL to https://swaggeroni-test.myeci.net/api/mcp in mcp.json (as shown above).
2. Leave out the headers block for OAuth2 auth code flow.
3. In your MCP client settings, configure OAuth2 Authorization Code (typically with PKCE) for this server.
4. Use the protected resource metadata at https://swaggeroni-test.myeci.net/api/.well-known/oauth-protected-resource so the client can discover the authorization server and required bearer method.
5. Ensure the OAuth app registration allows your MCP client redirect URI and required scopes.

Available MCP tools

These tools are exposed by the portal MCP server for API exploration and request construction.