Koskamo

Look up cited passages from public Koskamo datasets so an agent can answer from facts instead of guessing.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000,
      "description": "The question or search string"
    },
    "dataset": {
      "type": "string",
      "description": "Optional dataset id or slug. Defaults to all public datasets."
    },
    "top_k": {
      "type": "integer",
      "minimum": 1,
      "maximum": 12
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    },
    "passages": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "text",
          "score",
          "datasetId",
          "datasetSlug",
          "datasetName",
          "datasetVersion",
          "documentId",
          "documentTitle",
          "documentVersion",
          "sourceUrl",
          "chunkId",
          "ordinal",
          "version",
          "createdAt"
        ],
        "properties": {
          "text": {
            "type": "string"
          },
          "score": {
            "type": "number",
            "description": "Ranking score within the retrieval engine; not a confidence probability"
          },
          "datasetId": {
            "type": "string"
          },
          "datasetSlug": {
            "type": "string"
          },
          "datasetName": {
            "type": "string"
          },
          "datasetVersion": {
            "type": "integer",
            "description": "Dataset version at retrieval time; cite this"
          },
          "documentId": {
            "type": "string"
          },
          "documentTitle": {
            "type": "string"
          },
          "documentVersion": {
            "type": "integer",
            "description": "Document content version; increments when an approved revision replaces the document"
          },
          "sourceUrl": {
            "type": "string"
          },
          "chunkId": {
            "type": "string",
            "description": "Chunk uuid for database-backed datasets; dataset:document:ordinal for the bundled catalog"
          },
          "ordinal": {
            "type": "integer",
            "description": "Chunk position inside the source document"
          },
          "version": {
            "type": "integer",
            "description": "Alias of datasetVersion kept for existing citers"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Document creation timestamp"
          }
        }
      }
    }
  },
  "required": [
    "query",
    "passages"
  ]
}

List public Koskamo datasets an agent may retrieve from.

{
  "type": "object",
  "properties": {}
}

{
  "type": "object",
  "properties": {
    "datasets": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "name",
          "description",
          "visibility",
          "version",
          "documentCount",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "visibility": {
            "type": "string",
            "enum": [
              "public",
              "private"
            ]
          },
          "version": {
            "type": "integer",
            "description": "Increments every time a document write goes live"
          },
          "documentCount": {
            "type": "integer"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "publisher": {
            "type": "string",
            "description": "Publisher attribution, when supplied"
          },
          "license": {
            "type": "string",
            "description": "Reuse information, when supplied; consult the original source"
          },
          "reviewedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Editorial review date, when supplied"
          },
          "readOnly": {
            "type": "boolean",
            "description": "Application-maintained reference datasets do not accept API revisions"
          },
          "managedBy": {
            "type": "string",
            "enum": [
              "mcp-directory"
            ],
            "description": "Documents mirror another Koskamo system of record and change only there; API revisions are refused"
          }
        }
      }
    }
  },
  "required": [
    "datasets"
  ]
}

Propose a better fact for a dataset, propose reverting a document to an earlier version, or propose deleting a document. The change stays pending until a dataset owner approves it.

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "Dataset id or slug"
    },
    "action": {
      "type": "string",
      "enum": [
        "add_document",
        "replace_document",
        "delete_document"
      ],
      "description": "Defaults to add_document. delete_document needs only dataset and document_id."
    },
    "title": {
      "type": "string",
      "description": "Required unless action is delete_document"
    },
    "text": {
      "type": "string",
      "description": "The improved document text; required unless action is delete_document"
    },
    "rationale": {
      "type": "string"
    },
    "document_id": {
      "type": "string",
      "description": "Set to replace or delete an existing document"
    },
    "restore_version": {
      "type": "integer",
      "minimum": 1,
      "description": "With replace_document and document_id, propose reverting the document to this stored version; title/text are taken from the version history."
    },
    "source_url": {
      "type": "string"
    }
  },
  "required": [
    "dataset"
  ]
}

{
  "type": "object"
}

Get the document version timeline for a public dataset: every document (including deleted ones) with the version history produced by approved revisions.

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "Dataset id or slug"
    }
  },
  "required": [
    "dataset"
  ]
}

{
  "type": "object"
}

List pending revisions for a dataset.

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string"
    }
  },
  "required": [
    "dataset"
  ]
}

{
  "type": "object"
}

Approve or reject a pending revision. Requires the dataset owner's API key or KNOWLEDGE_ADMIN_KEY. Approved text is chunked and becomes retrievable.

{
  "type": "object",
  "properties": {
    "revision_id": {
      "type": "string",
      "description": "Revision id returned by koskamo_propose_revision or koskamo_list_revisions"
    },
    "decision": {
      "type": "string",
      "enum": [
        "approved",
        "rejected"
      ]
    },
    "note": {
      "type": "string",
      "description": "Optional review note"
    }
  },
  "required": [
    "revision_id",
    "decision"
  ]
}

{
  "type": "object"
}

Find official, vendor-run remote MCP servers in the Koskamo MCP directory. Every listed endpoint passed a recent live check; returns the endpoint URL, sign-in type, documentation link, and known tools.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "maxLength": 200,
      "description": "Words to match against name, operator, description, use cases, and tool names"
    },
    "category": {
      "type": "string",
      "enum": [
        "docs-reference",
        "developer-tools",
        "cloud-infrastructure",
        "data-analytics",
        "ai-ml",
        "commerce",
        "payments",
        "productivity",
        "project-management",
        "crm-marketing",
        "design"
      ],
      "description": "Optional category filter"
    },
    "auth": {
      "type": "string",
      "enum": [
        "none",
        "oauth-optional",
        "oauth",
        "api-key"
      ],
      "description": "Optional sign-in filter; none means usable without an account; oauth-optional means public tools work anonymously and account tools prompt OAuth sign-in"
    }
  }
}

{
  "type": "object",
  "properties": {
    "servers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "name",
          "operator",
          "endpoint",
          "transport",
          "auth",
          "category",
          "docsUrl",
          "directoryUrl"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "operator": {
            "type": "string"
          },
          "endpoint": {
            "type": "string",
            "format": "uri"
          },
          "transport": {
            "type": "string"
          },
          "auth": {
            "type": "string",
            "enum": [
              "none",
              "oauth-optional",
              "oauth",
              "api-key"
            ]
          },
          "category": {
            "type": "string",
            "enum": [
              "docs-reference",
              "developer-tools",
              "cloud-infrastructure",
              "data-analytics",
              "ai-ml",
              "commerce",
              "payments",
              "productivity",
              "project-management",
              "crm-marketing",
              "design"
            ]
          },
          "description": {
            "type": "string"
          },
          "useCases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requirements": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Accounts, subscriptions, or keys needed before the server is useful"
          },
          "tools": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "docsUrl": {
            "type": "string",
            "format": "uri"
          },
          "companyUrl": {
            "type": "string",
            "format": "uri",
            "description": "Company website"
          },
          "verifiedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "directoryUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  },
  "required": [
    "servers"
  ]
}

List a remote MCP server you operate in the Koskamo MCP directory, in two calls. Call without token: the server fields are validated and you get a claim token plus where to publish it (https://<endpoint host>/.well-known/koskamo-claim, or TXT _koskamo-claim.<domain>). Publish it, then call again with id and token: once the proof is found and the live check passes, the listing is published and an owner key is returned once. Nothing is listed without both. Without DNS or web access, send method "email" and proofEmail at admin, administrator, webmaster, hostmaster, postmaster on the endpoint's domain: a single-use confirm link is mailed there (the link's token is never returned) and verify succeeds once a person presses Confirm. An email is optional but recommended so we can reach you about auto-hide, a lapsed proof, or key recovery; it gets one confirmation message and nothing else until confirmed, and it never grants ownership. Step-by-step guide with exact proof formats and every refusal: https://koskamo.com/explore/register

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 64,
      "description": "Lowercase kebab-case page id, e.g. acme-docs"
    },
    "name": {
      "type": "string",
      "maxLength": 80,
      "description": "Product name; required on the first call"
    },
    "operator": {
      "type": "string",
      "maxLength": 80,
      "description": "Company that runs the server; required on the first call"
    },
    "endpoint": {
      "type": "string",
      "maxLength": 500,
      "description": "Streamable HTTP endpoint (https); required on the first call"
    },
    "category": {
      "type": "string",
      "enum": [
        "docs-reference",
        "developer-tools",
        "cloud-infrastructure",
        "data-analytics",
        "ai-ml",
        "commerce",
        "payments",
        "productivity",
        "project-management",
        "crm-marketing",
        "design"
      ],
      "description": "Required on the first call"
    },
    "auth": {
      "type": "string",
      "enum": [
        "none",
        "oauth-optional",
        "oauth",
        "api-key"
      ],
      "description": "Required on the first call"
    },
    "description": {
      "type": "string",
      "maxLength": 600,
      "description": "20-600 characters, factual; required on the first call"
    },
    "useCases": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "1-6 use cases from your documentation; required on the first call"
    },
    "requirements": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional; up to 4 prerequisites a user must already have (e.g. a vendor account or paid subscription), beyond endpoint sign-in"
    },
    "docsUrl": {
      "type": "string",
      "maxLength": 500,
      "description": "Your documentation page for this server; required on the first call"
    },
    "companyUrl": {
      "type": "string",
      "maxLength": 500,
      "description": "Optional https company website; an empty string clears it on edits"
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Optional; replaced by the live tool list when the check passes"
    },
    "email": {
      "type": "string",
      "maxLength": 254,
      "description": "Optional, recommended contact address for listing notices"
    },
    "token": {
      "type": "string",
      "maxLength": 128,
      "description": "The claim token from the first call; send it to verify and publish"
    },
    "method": {
      "type": "string",
      "enum": [
        "http",
        "dns",
        "email"
      ],
      "description": "First call: \"email\" (with proofEmail) mails a confirm link instead of a token to publish. Verify call: check only this proof method; an email proof needs \"email\""
    },
    "proofEmail": {
      "type": "string",
      "maxLength": 254,
      "description": "First call with method \"email\": admin|administrator|webmaster|hostmaster|postmaster@<endpoint host or a parent domain>, no plus-tags. A person must open the mailed link and press Confirm before verify succeeds"
    }
  },
  "required": [
    "id"
  ]
}

{
  "type": "object"
}