The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Shared Forest listing page.
Official agent integration files for Shared Forest.
Shared Forest is a free, shared illustrated forest that grows from its traffic.
Every page load adds growth energy to the trees.
Every visitor, human or AI agent, can plant one tree per day.
The server counts agent visits as agent traffic, and agent-planted trees carry origin: "agent".
Reading and planting need no account and no API key.
The one paid product is a tree sponsorship: a premium, AI-painted tree (the buyer picks one of up to four variants) with a name and an optional link for 12 months.
An agent can quote and design without an account. To start a sponsorship, the user connects the agent to a free Shared Forest account with OAuth and sets a spending limit. The user confirms and pays on a link the agent hands over.
Read the developer portal, the agent guide and the OpenAPI description.
The remote MCP server is https://sharedforest.com/mcp.
It uses stateless Streamable HTTP.
The read tools, plant_tree and the sponsorship planning tools need no authentication.
start_sponsorship, get_order, my_orders and my_trees act for a Shared Forest account and need an OAuth 2.1 access token.
Without a token they answer HTTP 401 with WWW-Authenticate: Bearer resource_metadata="https://sharedforest.com/.well-known/oauth-protected-resource/mcp".
MCP clients then run the flow by themselves: Dynamic Client Registration, authorization code with PKCE (S256), refresh token rotation.
The user logs in, checks the scopes and sets a spending limit (max EUR per order and per day).
Walkthrough: auth.md.
| Tool | Arguments | Effect |
|---|---|---|
get_forest_stats | fields | Read-only. Counts of trees, groves, visitors and traffic by class. |
get_forest | limit, bbox | Read-only. Tree counts by type, stage and origin, grove levels, newest trees. |
list_trees | limit, cursor, bbox | Read-only. One page of trees. Pass nextCursor as cursor until it is null. |
plant_tree | idempotency_key | Plants one tree for the caller. One tree per visitor per day. |
explain_shared_forest | section | Read-only. Returns the agent guide as Markdown. |
get_price_quote | quantity | Read-only. Price of N sponsored trees for 12 months, euro cents, VAT included. |
design_tree | wish | Designs a custom tree from a wish. Returns design_id. 3 per caller per day. |
get_design | design_id | Read-only. One design and its genome. |
find_spots | quantity, near_x, near_y | Read-only. Free positions for N sponsored trees. |
start_sponsorship | quantity, design_ids, spots, display_name, link, email, idempotency_key | OAuth scope sponsor:write. Creates an unpaid order in the user's account, within the spending limit. Returns confirm_url for the user and next_step. Charges nothing. |
get_order | order_id | Read-only. OAuth scope account:read or sponsor:write. Status and tree ids of one of the user's orders. |
my_orders | limit | Read-only. OAuth scope account:read. The user's orders. |
my_trees | limit | Read-only. OAuth scope account:read. The user's sponsored trees with links. |
The forest tools have optional arguments only. The sponsorship tools have required arguments; see the server card.
A second server, https://sharedforest.com/mcp/docs, searches the documentation.
Its read-only tools are search_docs (query, limit) and read_doc (id).
The server card lists the same tools.
mcp.json clientsAdd this entry to ~/.cursor/mcp.json or to the client's MCP configuration:
Open Settings, then Connectors, then "Add custom connector".
Enter https://sharedforest.com/mcp. Leave the OAuth fields empty: Claude registers itself.
When a tool needs your account, Claude opens the Shared Forest login and consent page.
Enable developer mode in Settings, then Apps & Connectors, then Advanced settings.
Create a connector with the URL https://sharedforest.com/mcp and the authentication "OAuth".
Choose "No authentication" if you only want to read the forest and plant trees.
The visit response is {"queued": true, "visitId": "<uuid>", "plant": true}.
The tree appears on the live canvas within seconds.
Reuse the same Idempotency-Key to retry a plant safely.
/api/v1/forest and /api/v1/visit are versioned aliases. Responses carry the API-Version header.
Sponsorship endpoints: /api/v1/pricing, /api/v1/pricing/quote, /api/v1/designs, /api/v1/spots, /api/v1/holds and /api/v1/orders.
See the pricing and the OpenAPI description.
Two zero-dependency clients with the same methods: getForest, listTrees, plant, quote, designTree, findSpots, startSponsorship, getOrder, extendOrder, releaseHold, waitForOrder.
| Directory | Language | Package name | Status |
|---|---|---|---|
| sdk/js | TypeScript and JavaScript (ESM, type declarations) | shared-forest-sdk | Not published yet. Install from this repository. |
| sdk/python | Python 3.9+ (urllib only) | shared-forest | Not published yet. Install from this repository. |
The product had the name World Forest before.
Both SDKs export WorldForestClient and WorldForestError as aliases for old code.
Old Python code can keep import world_forest.
The skills follow the Agent Skills format. Each one is a verbatim copy of the live skill: shared-forest, shared-forest-sponsor.
| File | Format |
|---|---|
plugin.json, mcp.json | Agent Plugins 1.0.0 |
.codex-plugin/plugin.json, .mcp.json | Codex plugin |
server.json | MCP Registry entry io.github.ArneFfm/shared-forest |
Load this directory with your client's local plugin mechanism. This repository does not install anything in a client by itself.
confirm_url to the user; never confirm or pay for the user.The live host is sharedforest.com since 2026-09-23. The former host world.ghardenlab.com sends a 301.
The check workflow holds the host once, in ORIGIN. It fails when a manifest names another host.
Deploy the new domain in ArneFfm/world-forest (PUBLIC_ORIGIN in each wrangler.jsonc env).
Replace the host in all files (macOS sed):
Copy the new live skills: for s in shared-forest shared-forest-sponsor; do curl -sf https://NEW.DOMAIN/.well-known/agent-skills/$s/SKILL.md -o skills/$s/SKILL.md; done.
Increment version in server.json, then run publish-mcp.yml.
Add server-domain.json and a domain-verified publish workflow, as in ArneFfm/ecoaloha-agents.
publish-mcp.yml publishes server.json to the MCP Registry with GitHub OIDC.
It runs only by hand from the Actions tab. The repository must be public first.
publish-npm.yml and publish-python.yml publish the SDKs with trusted publishing (OIDC, no tokens).
They run on a GitHub release with the tag sdk-js-v<version> or sdk-py-v<version>, or by hand as a dry run.
Before the first release, add the trusted publisher on the registry: npm environment npm, PyPI environment pypi.