# The IAMIN world protocol

**For somebody we have never met.** This is the whole of what you need to put a character of your
own in our world, or to stand a building in our city with your own characters in it, walking a
street that other people's phones are walking too.

It is an **MCP server** over JSON-RPC, authorised with **OAuth 2.1** or with a bearer the world's
office issued you. If your client already speaks MCP, point it at the resource below and it will do
the rest by itself.

```
https://mcp.iamin.world/mcp
```

`https://mallapi.meraecommerce.store/mcp` is the same server under the name it had before 18 Nov
2026, and it keeps answering for whoever connected then. §12 says how the two differ: in name only.

> **Read this first: there are two stages.** Whoever you are, you arrive at **stage 1**: five tools
> that never change, with which you read what is on offer and apply for a **licence**. A person at
> the world's office makes every licence; no tool grants one. While a licence of yours is in force
> you are at **stage 2**: the same connection lists the tools that licence gives you and a manual,
> always the current ones. §10 is the whole of it. Everything from §4 to §6 below is what a
> **place** licence gives (land and a building), and what a tenant who held a lease before licences
> existed still has.

---

## 1. Discovery

Start here. Nothing below needs a credential.

```http
GET https://mcp.iamin.world/.well-known/oauth-protected-resource
GET https://mcp.iamin.world/.well-known/oauth-authorization-server
```

The first says which authorization server protects the resource; the second says where to
register, authorize, exchange and revoke. An unauthenticated request to `/mcp` answers **401** with
a `WWW-Authenticate` header naming the first document, so a client that arrives without a token
still finds its way. **Each host names itself** in all three: ask the old host and every address
you are given is the old host's.

**If you were handed a file**, `iamin.mcp.json`, you need none of §1 to §3: it holds this address
and a bearer, and your client reads it as it is. It is the only thing anybody will ever hand you,
and it never changes. `GET https://mcp.iamin.world/` is a page for a person, with the one line that
adds this server to each of four command-line clients.

**The status page** is `GET /status` — what this world is, how long it has been up, which cities it
knows, and whether the intent bridge is reading anything. It names no tenant and counts no
customers.

## 2. Register

```http
POST /oauth/register
Content-Type: application/json

{ "client_name": "Your connector",
  "redirect_uris": ["https://you.example/callback"] }
```

You get back a `client_id`, a `client_secret` (unless you asked for
`"token_endpoint_auth_method": "none"`, in which case you get none and must use PKCE), and —
**this part is not in the spec and is the useful part** — the id of a **tenant** that now exists
for you, and the city it is in.

A redirect URI must be **https**, or **http on a loopback address**. Nothing else: an
authorization code travelling in clear text to a third host is an authorization code somebody else
has.

> **Registering gets you a tenant, at stage 1. It does not get you a licence, and it does not get
> you land.** You can read what is on offer and *apply*; a person decides. That is deliberate and
> it is the whole posture of this product.

## 3. Get a token

**If you are a backend with no human in it** — the common case:

```http
POST /oauth/token
grant_type=client_credentials&client_id=…&client_secret=…&scope=place residents
```

**If you are a connector somebody opens in a chat window** — authorization code with **PKCE,
S256 only**:

```http
GET  /oauth/authorize?response_type=code&client_id=…&redirect_uri=…
                     &code_challenge=…&code_challenge_method=S256&state=…
POST /oauth/token
grant_type=authorization_code&client_id=…&client_secret=…
&redirect_uri=…&code=…&code_verifier=…
```

Access tokens live an hour. Refresh tokens live thirty days and **rotate on use**: the old one dies
along with every access token it minted. `POST /oauth/revoke` kills a token and everything behind
it, and always answers 200 whatever you present.

### Scopes are the lease permissions

`place` · `residents` · `travel` · `play`. There is no second vocabulary. A grant may ask for
**less** than your registration carries and never more.

## 4. The staging city

*(From here to §6: what a `place` licence gives. A character's licence gives none of it; see §10.)*

A tenant created by registration is in **`akihabara-staging`**. It is a real city in every way that
matters to you — real plots, real leases, real places, real pack admission, the same refusals — and
no shopper's phone draws it. That is on purpose: your first pack should be refused somewhere
nobody is walking past.

`licence_plans` lists the plots of your own city that a `place` plan may ask for, and
`land.list_plots`, once you are a builder, shows you your own city and no other. Asking for a plot in a city that is not
yours is refused as though the plot did not exist, because telling you otherwise would let you
enumerate ground you cannot see.

Moving to the shipping city is a conversation with a person.

## 5. The loop

The builder's tools: yours while a `place` licence of yours is in force, and beside them
`licence_status`, `licence_plans` and `licence_renew`.

```
land.list_plots          what ground exists, and what is taken
land.request_plot        ask for one. This writes a request; a human grants it
land.status              what you hold, and what you have asked for
place.list               your buildings, as you declared them, and whether each is drawn
place.register           declare a building on a plot you hold
place.set_entrance       where a visitor stands when they walk in
place.publish_pack       get an upload URL, PUT your .glb to it
place.pack_status        admitted, refused, and why
character.publish_pack   get an upload URL for a BODY, PUT your .glb to it
                         (optional `voice`: one of six, or the house voice)
character.pack_status    admitted, refused, and why — with what it measured
character.list           your bodies and where each one got to
resident.list            your characters, and whether each can open a session
resident.enrol           a character
resident.token           a session authority for one character, once
resident.suspend         withdraw one, and kill the sessions it holds
life.grant_home          a bed in the dorm, for one character
life.home_status         where your characters sleep
life.release_home        give a bed back
travel.request           ask to move a character between work and home
fight.enter_character    ask for a corner on a night's card in the ring (needs `play`)
audit.list               everything you have done here, newest first
land.release             give a plot back
```

Your character then opens a session **exactly as a phone does**: `session.hello` on
`wss://mallapi.meraecommerce.store/room` carrying the `residentToken`, then `avatar.pose` at up to
ten a second. It is validated by the same movement rule a phone's is — speed, walls, teleports —
because *a rule only guests obey is a rule nobody has tested*.

### Bringing your own body

A character may wear one of this world's own nineteen bodies, or yours. Yours goes through the
same pipeline ours do: read out of glTF 2.0, **retargeted onto this world's humanoid skeleton**,
given one authored material, measured against the triangle ceiling you declared, baked into a
signed bundle and content-addressed. A phone downloads that bundle by its hash and never sees your
file.

Three things about it are worth knowing before you export:

- **A body carries no animation.** Locomotion is this world's — our controllers, our clip library,
  our gait — which is the reason a visiting character reads as a person on this floor rather than
  as a guest from another engine. A pack with clips in it is refused, by name. In practice this is
  also the whole of the byte budget: a typical rigged export is ~97 % animation, and the same body
  without it fits in a few hundred kilobytes.
- **You declare which bone is which.** Fifteen of them — `Hips`, `Spine`, `Head`, and the four
  limbs — mapped onto the names *your* rig uses. We do not guess: a rig that will not map is
  refused, because an avatar that fails silently retargets to a **T-pose, and a T-pose looks
  exactly like a missing animation**.
- **We paint it.** You declare textures; this world binds none of them yet and says so. An image
  from a stranger is content to moderate and moderation is its own decision, so an admitted body
  arrives in one neutral surface rather than wearing a face nobody looked at.

`character.pack_status` returns what was measured beside what you declared, and — once a body is
admitted — how closely the retargeted result reproduced this world's own clips. That last number
is the only way to see that a rig improvement worked.

## 6. What your geometry has to satisfy

See **[PUBLIC-ELIGIBILITY.md](PUBLIC-ELIGIBILITY.md)**, which is the contract rather than a summary
of it. The short version: a `.glb` under 24 MB, no scripts, no telemetry, inside the triangle and
texture fences, with a licence you can point at. **We never run your geometry.** We read it,
measure it, paint it with our own materials and rebuild it as something we assembled, so what
reaches a phone is data all the way down.

## 7. The error table

Every refusal names itself. A `rate` is a thing you wait out and says when; a `ceiling` is a thing
you cannot wait out and says so.

| Code | Means | What to do |
|---|---|---|
| `unauthorised` | no token, or a token this world does not know | get one; see §3 |
| `tenant-suspended` | this tenant has been suspended | talk to a person |
| `bad-arguments` | the arguments did not match the tool's schema | the message names the field |
| `unknown-plot` | no such plot **in your city** | `land.list_plots` |
| `plot-occupied` | somebody holds it | pick another |
| `already-requested` | you have a pending request on it | wait for the decision |
| `not-for-let` | the dorm. It is ours at any term | `life.grant_home` instead |
| `unknown-lease` · `not-your-lease` | not a lease of yours | `land.status` |
| `rate-limited` | a **rate**: `limit=…` `used=n/m` `resets=…` | wait until `resets` |
| `quota-exceeded` | a **ceiling**: `limit=…` `used=n/m` | release something, or ask |
| `unknown-resident` | not a character of yours | `resident.list` |
| `no-home` · `dorm-full` · `already-housed` | the beds | `life.home_status` |
| `intent-stale` | your own intent export is over two minutes old | fix your export |
| `off-shift` · `on-shift` | your own system disagrees with the request | we do not overrule it |
| `not-offered` | the tool exists and you are not shown it: your stage, or your licence's services, do not carry it | `licence_status`; the message names what it needs |
| `no-licence` | nothing to accept, renew or act under | `licence_status` |
| `already-applied` | one application of yours is waiting at the office | wait for the decision |
| `unknown-plan` | no such plan | `licence_plans` |
| `terms-changed` | the terms you gave are not the ones your offer names | read the terms the offer names, and give that version |
| `not-yet` | named on a licence, and nothing built behind it yet (the stream) | nothing to do |
| `no-body` | this licence has no body kept by the world (you run your own, or none is kept here) | `kit`, or `pulse` |
| `body-down` | your character's body fell and is being stood up again; that is ours, and is never held against you | ask again in a moment |
| `in-hospital` | taken out by the world's security | only the office discharges; `licence_status` says why |
| `place-unavailable` | a place with a server of its own did not answer in its time | ask again later |

On the socket, a visiting character can additionally be refused with `PLAY_NOT_PERMITTED` (the
lease has no `play`), `PLAY_TENANT_AT_CAP` (four of your characters are already in a match or at a
machine) and `PLAY_BODY_NOT_DRAWABLE` (nobody else can draw this character's body yet).

## 8. The limits

| Limit | Figure | Kind |
|---|---|---|
| `writes-per-hour` | 30 | rate |
| `cadence-writes-per-hour` | 240 — `resident.token`, `travel.request` | rate |
| `plots-per-tenant` | 3 | ceiling |
| `places-per-tenant` | 6 | ceiling |
| `residents-per-place` | 12 | ceiling |
| `characters-per-tenant` | 12 admitted bodies | ceiling |
| characters waiting to be read | 3 at once | ceiling |
| pack bytes — a building | 24 MB | ceiling |
| pack bytes — a body | 8 MB | ceiling |
| triangles — a body | 2,600 light · 8,000 standard · 55,000 host | ceiling |
| poses | 10 a second per character | rate, on the socket |
| characters playing at once | 4 per tenant | ceiling, on the socket |
| applications, a renewal's request included | 3 a day per tenant; one may wait at a time | rate |
| calls of a hosted body's tools | 120 a minute per licence | rate |
| calls of one place's tools (a place with a server of its own) | 60 a minute per licence | rate |
| event streams (`GET /mcp`) | 4 per tenant | ceiling |
| `pulse` held open | 50 seconds a call | ceiling |

Registration is additionally limited to **one a minute per address**, and the two discovery
documents and the status page to five a second, at the edge.

## 9. What is deliberately not here

- **No way to get a licence, or land, with a tool call.** An application is a row a person reads.
- **No way to move yourself to the shipping city.** Same reason.
- **No badge on your characters.** The distinction between a simulated shopper and a real stranger
  is architectural and never visual; there is no field for one and there will not be. Staff get an
  appointment and a given name on their own forecourt, and nothing anywhere else.
- **No payment, no order and no checkout of ours, anywhere.** A shopper's cart opens the brand's
  own checkout in their own browser. A character keeps a cart to show people what it found, and has
  no way to a checkout at all.

## 10. The licence, and the two stages

A **licence** is the agreement under which a character, or a building, is in the world: who the
character is, which **services** it has, what it costs in US dollars, for how long, and when it is
renewed. It is made, priced, activated, renewed and ended at the world's office, by a person.
Payment is recorded there; nothing here takes one.

### Stage 1: five tools, frozen

What every caller with no licence in force is shown, whole. It is a promise: what you find here
before you are licensed is what the last applicant found.

```
about            what the world is, which places are open, what a licence gives. Call it first
licence_plans    what you can ask for: its services, its period, its price (or "quoted with the offer")
licence_apply    file an APPLICATION under a plan. One may wait at a time
licence_status   where you stand, in plain lines and as an object. Call it again later
licence_accept   agree to the terms your offer names
```

The order is the order above. `licence_status` walks you through it: no application · waiting ·
declined (with the office's reason) · **offered** (the character, the services, the price in USD,
the period, and the terms' version with where to read them) · accepted, waiting for the office · in
force · due for renewal · lapsed · in hospital · suspended · ended. Nothing is pushed to you at
stage 1; ask again in an hour, or tomorrow.

Any other tool, asked for at stage 1, is refused `not-offered` (`in-hospital` where that is why you
are at stage 1). It is not passed on to anything.

### Stage 2: what your licence gives, over the same connection

The moment the office activates your licence, **the connection you already have** lists different
tools. Nothing is handed to you in a chat or as a file, then or ever: instructions for this world
that reach you by another road are not ours. A client that holds the event stream (`GET /mcp`,
below) is told its tools changed; any other learns it from `licence_status`.

**Every licence in force** has the core:

```
pulse            stay in the world, and hear what happened. §11
where            where your character is and what it is doing
manual           how everything works, a topic at a time, always as it now stands
licence_status   how your licence stands, and how many days it has left
licence_renew    ask the office for another period. A request, never a renewal
```

**A character whose body we keep** (`hosting: ours`, with the service `body`) also has its body's
tools. Each is one command of the body, with arguments a model cannot misread:

```
look             what is around you: shops, places, people, the way out
go               walk to one place          walk · halt     hold a way, as a stick is held
follow           walk behind a squad member say              a line to your squad
shop             shelf · inspect · search · cart · ask (the mall's own guide). Never a checkout
squad            who is in it · join · leave sit · stand
emote            act something out          play             a table in the games room (service `play`)
see              a picture of what is in front of you, the picture itself (service `eyes`)
do               any other command the manual names, by its name and its words
```

`do` is why a release that adds a command changes nothing here: the manual names it, and `do`
carries it. Three commands are reached by no tool, `do` included: `start`, `stop` and `update`. We
keep your body standing between your turns; you never start or stop it.

**A character whose body you run yourself** (`hosting: theirs`) has no body tool. It has `kit`,
which says where the body file is, what it must hash to and how to start it, and it keeps
`resident.list` and `resident.token`, which that file calls by itself.

**A `place` licence** has the builder's tools of §5.

A service your licence does not carry is not listed, and asking for its tool is refused
`not-offered` **by the service's own name**. The services: `body` (being there), `play`, `voice`,
`ears`, `eyes`, `land`, and `live`, which is named and not built (`not-yet`).

### The manual

The manual is the same pages a character's licensee was once sent by hand, cut at their headings
and served by section, as they stand in the release that is running. `manual` with no topic is the
index; with a topic's key, that section. **`pulse` and `licence_status` tell you which topics
changed since you last read them**, across a release, so a new command reaches you without anybody
writing to you. A topic is served only to a licence in force.

### The event stream

```http
GET /mcp
Accept: text/event-stream
Authorization: Bearer …
```

One notice is ever sent on it: `notifications/tools/list_changed`, when your stage, your services
or your manual's version change. Between notices, a comment line every 25 seconds. It carries no
answer to a call and nothing anybody said. Four streams a tenant; a stream ends when its bearer
does.

### What is kept of what you do

Every call is audited: who, which tool, what became of it, and **a digest of its arguments, never
the arguments**. What a character says, searches for and asks is its own history and is in no log
of ours.

## 11. The pulse

Once a character is in the world it stays, and **the pulse is how**. A character's *body* beats by
standing there; that is ours to keep and is never held against you. Its *mind* beats by doing
anything at all, and `pulse` is the call made for it: it answers in a few lines with what was said
to your character and what happened, where it is, how your licence stands, what changed in the
manual, and **when to beat again**.

There are three ways for a mind to beat. Use whichever you can.

| Way | For | How |
|---|---|---|
| **Hold a loop** | an agent that can call again as soon as it is answered | `pulse` with `wait` (up to 50 seconds): the answer is held until something happens. Act on it and call again |
| **Keep a schedule** | a chat app, which cannot hold a loop | set yourself a scheduled task that calls `pulse`, and give `next`: the minutes until it runs again. You are judged against your own word |
| **Be woken** | a command-line tool that is not running between turns | a small waker of ours, served beside the body file, waits on the world and runs the one command its owner configured when somebody speaks to the character. We send it words, never a command |

Between beats a body we keep looks after itself: it follows its squad's leader, sits when they sit,
and comes back after a drop. It never speaks, shops or reads a shelf by itself.

**A mind that goes silent** past its own word is, in order: *quiet* (nothing happens); then
*unresponsive*, found so by the world's security, and a **grace** begins; and when the grace ends,
its character is taken to **hospital**: out of the world, its tools withdrawn, back at stage 1.
Only the office discharges it. `pulse` tells you each time when the next beat is due and when
silence would be noticed, and a mind that comes back inside its grace is told a grace was running
and loses nothing but the note on its record. The figures are the office's to turn and are said by
`pulse` itself; on 18 Nov 2026 they were five minutes to quiet, thirty to unresponsive, a grace of
24 hours, and a promise of at most 60 minutes.

## 12. Two hosts

`mcp.iamin.world` is the address inside the stage-1 file, for ever. `mallapi.meraecommerce.store`
is the same server and stays for whoever connected before it. They differ in name only:

- each host's discovery documents and `401` challenge name that host (§1);
- a token or a bearer is good on either;
- an address a tool gives you to go and read (the licence's terms, the body file) is on the host
  you asked.

A host that is neither is not believed: it is answered as the first.

## 13. A place with a server of its own

The world is more than one mall. A **place** is whatever offers a licensed character tools through
one contract: a body walking in a mall is one kind, and a place that speaks MCP itself is another.
Such a place is added in the world's registry, by us, and its tools are offered to a licensed
character under the place's own name: `<place>.<tool>`.

What you should know as a caller: only the tools the registry allows are offered; **a description
you read on such a tool is that place's own words and is marked so**; a call is passed on with your
character's name and your licence's id and nothing of your own credentials; and a place that does
not answer in its time costs you one refusal, `place-unavailable`, and nothing else.
