MCP · Streamable HTTP

Project references, available to your tools.

Sourcefolio provides normalized open-source metadata and a private project-reference workspace through a remote Model Context Protocol server.

Server URLhttps://mcp.sourcefolio.io/mcp

TransportStreamable HTTP

AuthenticationPer-developer bearer key

Quickstart

Add the server URL and bearer header to any client supporting remote Streamable HTTP MCP:

{
  "url": "https://mcp.sourcefolio.io/mcp",
  "transport": "streamable-http",
  "headers": {
    "Authorization": "Bearer ${SOURCEFOLIO_API_KEY}"
  }
}

Confirm reachability independently of authentication:

curl https://mcp.sourcefolio.io/healthz
# {"status":"ok"}

Join the private beta

Request developer access

Tell us about your team and workflow. We will create your workspace and issue an individually scoped API key.

Ask to join the beta

Authentication

API keys are issued per developer and map to one isolated Sourcefolio workspace. Store the key as a secret and send it on every MCP request.

Authorization: Bearer sfk_...

Keys are read-only by default. Workspace mutation requires a separately issued key containing the workspace:write permission.

Key lifecycle

Do not place keys in source control, URLs, or client logs.
Use separate keys for local development, CI, and each collaborator.
Ask your workspace administrator to revoke and replace a lost key.

Access administration

Each developer uses an individually issued credential connected to one workspace. Company-wide shared keys are not supported.

Workspace owners manage members, roles, and credential lifecycle through the workspace administration portal. These controls are intentionally outside MCP so connected tools cannot grant access or rotate credentials.

Tools

Examples show tool arguments and the JSON value returned inside MCP text content.

`search_public_projects`

Search verified npm, PyPI, Cargo, Maven, and Go projects by name or repository URL. Optionally restrict results to one ecosystem.

Requires catalog:read

Payload

{ "query": "Django", "ecosystem": "pypi" }

Response

[{ "project_id": "public:django", "name": "Django", "ecosystem": "pypi", "license": "BSD-3-Clause", "release_version": "5.2" }]

`get_public_project`

Retrieve one complete public catalog record using its stable Sourcefolio project identifier.

Requires catalog:read

Payload

{ "project_id": "public:zod" }

Response

{ "project_id": "public:zod", "name": "Zod", "ecosystem": "npm", "repository_url": "https://github.com/colinhacks/zod", "license": "MIT", "release_version": "4.1.12" }

`list_workspace_projects`

List up to 50 projects in the authenticated workspace. Pass the last project identifier as a cursor to continue.

Requires workspace:read

Payload

{ "cursor": "workspace:2f4c..." }

Response

[{ "project_id": "workspace:8a31...", "name": "Fastify", "status": "approved", "release_version": "5.6.2" }]

`get_workspace_project`

Retrieve a saved project, including its release metadata, workspace notes, and current official status.

Requires workspace:read

Payload

{ "project_id": "workspace:8a31..." }

Response

{ "project_id": "workspace:8a31...", "name": "Fastify", "ecosystem": "npm", "release_version": "5.6.2", "notes": "Platform review", "status": "approved" }

`add_workspace_project`

Add an evaluated project to the workspace. Name, ecosystem, and repository URL are required; release details and notes are optional.

Requires workspace:write

Payload

{ "name": "Fastify", "ecosystem": "npm", "repository_url": "https://github.com/fastify/fastify", "license": "MIT", "release_version": "5.6.2", "notes": "Evaluate for edge APIs" }

Response

{ "project_id": "workspace:8a31...", "name": "Fastify", "status": "evaluating", "notes": "Evaluate for edge APIs" }

`update_workspace_project`

Patch one or more mutable metadata fields on an existing workspace project without replacing the full record.

Requires workspace:write

Payload

{ "project_id": "workspace:8a31...", "patch": { "release_version": "5.7.0", "notes": "Upgrade after compatibility test" } }

Response

{ "project_id": "workspace:8a31...", "release_version": "5.7.0", "notes": "Upgrade after compatibility test", "status": "approved" }

`remove_workspace_project`

Remove a project from the authenticated workspace. Public catalog records are unaffected.

Requires workspace:write

Payload

{ "project_id": "workspace:8a31..." }

Response

{ "removed": true }

`get_current_identity`

Identify the current developer credential, associated workspace, and granted scopes without exposing the API key.

Requires authentication

Payload

{}

Response

{ "principal_id": "key:devkey123456", "label": "Alex development", "type": "api_key", "workspace_id": "account:team", "scopes": ["catalog:read", "workspace:read"] }

`get_current_workspace`

Describe the workspace bound to the current credential and provide its out-of-band administration location.

Requires workspace:read

Payload

{}

Response

{ "workspace_id": "account:team", "role": "member", "administration_url": "https://sourcefolio.io/login.html" }

`record_adoption_decision`

Append a member-attributed recommendation and notes to a project. Multiple members can record independent assessments.

Requires workspace:write

Payload

{ "project_id": "workspace:8a31...", "decision": "approved", "notes": "Passed load and compatibility testing" }

Response

{ "decision_id": "decision:91bf...", "project_id": "workspace:8a31...", "decision": "approved", "author_label": "Alex development", "notes": "Passed load and compatibility testing" }

`list_adoption_decisions`

Read member recommendations and notes across the workspace, optionally filtered by project or decision.

Requires workspace:read

Payload

{ "project_id": "workspace:8a31...", "decision": "approved" }

Response

[{ "decision_id": "decision:91bf...", "decision": "approved", "author_label": "Alex development", "notes": "Passed testing" }]

`set_project_status`

Set the workspace's official project state independently from individual recommendations. Valid values are evaluating, approved, rejected, and retired.

Requires workspace:write

Payload

{ "project_id": "workspace:8a31...", "status": "approved" }

Response

{ "project_id": "workspace:8a31...", "name": "Fastify", "status": "approved" }

Protocol notes

Send MCP messages to POST /mcp using JSON-RPC 2.0.
Advertise both application/json and text/event-stream in Accept.
Capture the mcp-session-id response header after initialization and return it on subsequent requests.
The current tested MCP protocol version is 2025-06-18.

Content-Type: application/json
Accept: application/json, text/event-stream
mcp-session-id: <session returned by initialize>

Errors

Status	Meaning
`400`	Invalid MCP message or protocol version.
`401`	API key is missing, invalid, expired, or revoked.
`404`	MCP session is missing or no longer available.
`406`	Required Streamable HTTP response types were not accepted.