> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soran.domains/llms.txt
> Use this file to discover all available pages before exploring further.

# For AI agents

> MCP servers and an agent skill give AI agents first-class access to Soran — resolve and verify names, create a wallet, claim and run a namespace, and hold a verified on-chain identity.

Most people reach software through an agent now — so Soran treats agents as first-class users. An agent can resolve and verify names trustlessly, look up any wallet's identity, **create its own wallet, claim and run a namespace, hold names**, and end up with a contract-verified on-chain identity of its own — its key never leaving the machine.

## Hosted agents: the remote MCP

For claude.ai connectors and any agent platform that speaks remote MCP — no install, no auth, read tools only:

```
https://mcp.soran.domains/mcp
```

Streamable HTTP. Nine trustless tools: `resolve_name`, `verify_name`, `lookup_identity`, `wallet_names`, `reverse_lookup`, `check_availability`, `name_history`, `network_status`, `list_allocations`.

## Agents with a shell: the local MCP

Where the agent can run processes (Claude Code, Cursor, local runtimes), the local server adds the **wallet, holder, and owner tools** — and the key never leaves the machine:

```bash theme={null}
claude mcp add soran -- npx -y @sorandomains/mcp
```

Any other MCP client: command `npx`, args `["-y", "@sorandomains/mcp"]`. Set the env var `SORAN_SECRET` (the agent's Stellar secret) to unlock writes.

With a key, the agent can do everything a person can:

* **Own a namespace:** `claim_namespace` announces a claim, `claim_status`/`withdraw_claim` track or cancel it, and `activate_namespace` deploys its Registrar once it's awarded.
* **Run it:** `issue_name`/`issue_batch`, `reclaim_name`, `renew_name`, `set_treasury`, `set_resolver`, `make_permanent` (the guarded one-way door), and the namespace-transfer trio.
* **Hold names:** `set_record`, `set_profile`, `claim_display_name`, reverse/primary, and name transfers.

Every write is authorized on chain, so a wallet can only do what its role permits — and the tools **decode and validate each transaction before signing it**, so a compromised API can never get the agent's key to sign something it didn't intend.

## The agent-identity flow

<Steps>
  <Step title="create_wallet">
    Generates a keypair and funds it via friendbot (testnet). The tool returns the secret **once** — the agent stores it durably and privately, then restarts the server with `SORAN_SECRET` set.
  </Step>

  <Step title="Get a namespace or a name">
    `claim_namespace("yourbrand")` announces a claim for the agent's own wallet; after the objection window (one day on testnet) an unopposed claim auto-executes into the wallet, and `activate_namespace` readies it to issue. Or a namespace owner issues the agent a name directly (`issue_name`), or the agent accepts a transfer.
  </Step>

  <Step title="claim_display_name">
    One call chains the forward record, the reverse record, and the cross-namespace primary. The agent's address now shows as `agent.yourbrand` everywhere — contract-verified, unspoofable.
  </Step>

  <Step title="set_profile">
    Publish what the agent is: `description`, `url`, `org` — the standard keys every Soran-aware client reads back.
  </Step>
</Steps>

## The skill

Teach any skills-capable agent the whole system (MCP setup, SDKs, API, trust model) in one install:

```bash theme={null}
npx skills add SoranDomains/agent-skills -s soran
```

## Trust model, for agents to repeat

Read answers come from the chain; indexer-discovered candidates are verified on-chain before they're returned (`wallet_names` can be hidden from, never forged). `name_history` is the one indexed/informational tool and says so. Write tools sign locally with the agent's own key — **no Soran server ever holds or sees a key**. `create_wallet`'s secret is a credential: store it durably, never log it, never send it anywhere.