Skip to main content
Glama
nerdit-ai

Nerdit

Official
by nerdit-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

share_service

Expose a deployed app through a hosted URL, choosing private owner-only access or public world access, so the app can be opened outside the LAN.

Instructions

Use when: you need a URL you can open (public_url is LAN-only).

    Exposes the app at ``https://<name>--<slug>.<domain>/`` via the cloud
    link. ``access='private'`` (default) opens only for the owner of this
    machine's Nerdit account, signed in to the Nerdit App, and the people they
    allow there — works on every linked node, nothing to configure.
    ``access='public'`` makes the URL world-reachable: it needs an
    account in good standing (free during the public beta; else 409
    ``share.not_entitled``) AND either a
    ``[deploy].edge_auth`` on the app or ``consent=true`` (else 409
    ``share.unprotected``) — public means public. The node must be linked
    (409 ``share.link_required``). Returns ``{access, url, state}``; ``state``
    is ``ready`` | ``link_down`` | ``not_entitled``. The same URL then appears
    in ``get_service`` / ``list_routes`` under ``public_urls`` (kind
    ``hosted``).

    ``state`` and ``origin`` answer two DIFFERENT questions and you need
    both. ``state`` is about the LINK — is the hosted path provisioned.
    ``origin`` is about the APP behind it: ``{status, answers, hint}``, where
    ``answers`` is true only while the service is running. A share can be
    ``state: ready`` with ``origin.answers: false``, and then the URL returns
    ``share.not_shared`` (the hosted resolver refuses a service with no live
    origin) — which reads exactly like "never shared". When ``answers`` is
    false, ``origin.hint`` says what to do; call ``diagnose_service``.

Input Schema

NameRequiredDescriptionDefault
nameYesName (or row id) of an existing deployed app — only kind 'service' can be exposed: ``share_service``/``add_domain`` refuse a model or database with 422 ``*.kind_unsupported``, while the remove tools just find nothing to undo.
accessNoExposure mode: ``private`` (the default — only the owner of this machine's Nerdit account and the people they allow in the Nerdit App) or ``public`` (world-reachable). Any other value is refused by the daemon with a 422.private
consentNoAcknowledges that a public share serves the app to anyone with the URL. Read only when ``access='public'``, where ``false`` (the default) is refused unless the app carries a ``[deploy].edge_auth`` block; ignored for a private share.
hosted_onlyNo``true`` locks the app to its hosted URL: no local proxy route (409 ``share.hosted_only_conflict`` while a domain is bound, 409 ``share.hosted_only_no_token`` if the daemon is reachable without a token). ``false`` restores the LAN routes; omitted keeps the stored lock. With ``access='private'`` a lock request keeps an existing public share.
idempotency_keyNoCaller-chosen key: a retry with the same key replays the first result instead of acting twice. Omit and a fresh key is minted per call, so each call acts.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it enumerates the 409 failure codes (``share.not_entitled``, ``share.unprotected``, ``share.link_required``), explains the returned ``state`` values, and warns that ``state: ready`` with ``origin.answers: false`` still yields ``share.not_shared`` — a behavior an agent could not infer anywhere else.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the "Use when" line and organized by concern (modes, errors, return, state vs origin). It is long and occasionally chatty ("public means public"), but nearly every sentence delivers a distinct fact such as an error code or the state/origin distinction.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, and the description compensates by describing the return shape ``{access, url, state}``, the ``origin`` object's fields, and where the resulting URL surfaces (``get_service``/``list_routes`` under ``public_urls``). It also routes the agent to ``diagnose_service`` when ``answers`` is false.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description nonetheless adds meaning beyond the schema by tying ``access='private'`` to "works on every linked node, nothing to configure" and by making the entitlement/``consent`` gate for ``access='public'`` concrete. It says less about ``hosted_only`` and ``idempotency_key``, which the schema already documents well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (expose an app via the cloud link at a hosted URL) and immediately contrasts it with the LAN-only ``public_url``, so the agent can tell it apart from ``serve``/``add_domain`` without opening a schema. The private-vs-public framing pins down the scope precisely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with an explicit "Use when: you need a URL you can open" trigger and names the alternative that will not satisfy that need (``public_url`` is LAN-only). It also spells out the preconditions for each access mode (account in good standing, ``edge_auth`` or ``consent=true``, node linked). It stops short of naming ``unshare_service`` or stating when not to share at all.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools