Examplary MCP Server

Instructions

Implementation Reference

• src/server.py:96-101 (registration)

  The tool 'postExamsidSessionssessionIdGenerate_overall_feedback' is registered here as part of all tools generated from the OpenAPI specification of the Examplary API using FastMCP.from_openapi. The spec is fetched from https://api.examplary.ai/openapi and patched to remove certain endpoints.

  print("Creating MCP server from OpenAPI spec...", file=sys.stderr)
  mcp = FastMCP.from_openapi(
      openapi_spec=openapi_spec,
      client=client,
      name="Examplary"
  )

• src/server.py:86-93 (helper)

  HTTP client used by all generated tool handlers to make authenticated requests to the Examplary API endpoints, including the one for generating overall feedback in exam sessions.

  client = httpx.AsyncClient(
      base_url="https://api.examplary.ai",
      headers={
          "Authorization": f"Bearer {api_key}",
          "Content-Type": "application/json"
      },
      timeout=30.0
  )

• src/server.py:30-60 (helper)

  Patches the OpenAPI spec before tool generation, excluding certain endpoints like those related to API keys and OAuth, ensuring the generate_overall_feedback endpoint is available unless excluded.

  def patch_openapi_spec(spec: dict) -> dict:
      """Patch OpenAPI spec to fix validation issues and filter endpoints"""
      # Remove unwanted endpoints
      excluded_patterns = [
          "api-key",
          "api_key",
          "library",
          "libraries",
          "oauth"
      ]
  
      if "paths" in spec:
          paths_to_remove = [
              path for path in spec["paths"].keys()
              if any(pattern in path.lower() for pattern in excluded_patterns)
          ]
  
          for path in paths_to_remove:
              print(f"Excluding endpoint: {path}", file=sys.stderr)
              del spec["paths"][path]
  
          # Add missing description fields to response objects
          for path, path_item in spec["paths"].items():
              for method, operation in path_item.items():
                  if method in ["get", "post", "put", "patch", "delete"] and "responses" in operation:
                      for status_code, response in operation["responses"].items():
                          # Add description if missing
                          if isinstance(response, dict) and "description" not in response:
                              response["description"] = f"Response for {method.upper()} {path}"
  
      return spec

• src/server.py:63-104 (registration)

  Full function that fetches OpenAPI spec, patches it, creates HTTP client, and registers all tools via FastMCP.from_openapi.

  def create_server() -> FastMCP:
      """Create and configure the Examplary MCP server"""
      # Get API key
      api_key = get_api_key()
  
      # Fetch the OpenAPI specification
      print("Fetching OpenAPI specification...", file=sys.stderr)
      try:
          response = httpx.get("https://api.examplary.ai/openapi", timeout=30.0)
          response.raise_for_status()
          openapi_spec = response.json()
          print(f"Successfully loaded OpenAPI spec (version {openapi_spec.get('openapi', 'unknown')})",
                file=sys.stderr)
  
          # Patch the spec to fix validation issues
          print("Patching OpenAPI spec to fix validation issues...", file=sys.stderr)
          openapi_spec = patch_openapi_spec(openapi_spec)
  
      except Exception as e:
          print(f"ERROR: Failed to fetch OpenAPI spec: {e}", file=sys.stderr)
          sys.exit(1)
  
      # Create authenticated HTTP client
      client = httpx.AsyncClient(
          base_url="https://api.examplary.ai",
          headers={
              "Authorization": f"Bearer {api_key}",
              "Content-Type": "application/json"
          },
          timeout=30.0
      )
  
      # Create MCP server from OpenAPI specification
      print("Creating MCP server from OpenAPI spec...", file=sys.stderr)
      mcp = FastMCP.from_openapi(
          openapi_spec=openapi_spec,
          client=client,
          name="Examplary"
      )
  
      print("MCP server created successfully!", file=sys.stderr)
      return mcp