# thingctx

Turns W3C WoT Thing Descriptions and OpenAPI specs into agent tools. It gates every operation and executes requests without exposing credentials to the model.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 16
- Author: thingctx
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/thingctx/thingctx
- Updated: 2026-10-13
- HTML: https://affpapa.org/en/nevibecode/mcp/thingctx

## What it does

thingctx maps W3C Web of Things JSON descriptions or OpenAPI 3.x specs into agent tools named `<thing>__<action>`. Calls route directly across target protocols like HTTP, MQTT, or local handlers based on the address scheme in the description. No extra bridge is needed.

Secrets never reach the model prompt. Secrets stay local. The server handles authorization per operation, which lets you permit read actions while rejecting writes on the exact same target. The shipped `exec` subprocess transport is locked by default and refuses any command until supplied with an explicit allowlist.

The project requires Python 3.10 or later. While local and subprocess execution work immediately, extra features like Redis support and OpenAPI conversion require installing optional package extras.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `THINGCTX_POLICY`, `THINGCTX_APPROVE_WHEN`, `THINGCTX_FS_ROOT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env THINGCTX_POLICY=<THINGCTX_POLICY> --env THINGCTX_APPROVE_WHEN=<THINGCTX_APPROVE_WHEN> --env THINGCTX_FS_ROOT=<THINGCTX_FS_ROOT> --transport stdio thingctx -- uvx thingctx
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from thingctx <command>

### Codex

**Platform CLI**
```bash
codex mcp add thingctx --env THINGCTX_POLICY=<THINGCTX_POLICY> --env THINGCTX_APPROVE_WHEN=<THINGCTX_APPROVE_WHEN> --env THINGCTX_FS_ROOT=<THINGCTX_FS_ROOT> -- uvx thingctx
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from thingctx <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "thingctx": {
            "command": "uvx",
            "args": [
                "thingctx"
            ],
            "env": {
                "THINGCTX_POLICY": "<THINGCTX_POLICY>",
                "THINGCTX_APPROVE_WHEN": "<THINGCTX_APPROVE_WHEN>",
                "THINGCTX_FS_ROOT": "<THINGCTX_FS_ROOT>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from thingctx <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "thingctx": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "thingctx"
            ],
            "env": {
                "THINGCTX_POLICY": "<THINGCTX_POLICY>",
                "THINGCTX_APPROVE_WHEN": "<THINGCTX_APPROVE_WHEN>",
                "THINGCTX_FS_ROOT": "<THINGCTX_FS_ROOT>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from thingctx <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e THINGCTX_POLICY=<THINGCTX_POLICY> -e THINGCTX_APPROVE_WHEN=<THINGCTX_APPROVE_WHEN> -e THINGCTX_FS_ROOT=<THINGCTX_FS_ROOT> thingctx uvx thingctx
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from thingctx <command>

## When to use it
- expose local processes or hardware devices to agents via W3C WoT manifests
- import OpenAPI 3.x specifications directly into agent-callable toolsets
- prevent LLMs from directly touching API tokens during tool calls
- restrict subprocess commands using strict allowlists on the `exec` transport

## Example prompts
- Import `https://api.example.com/openapi.json` into a Thing Description file.
- Run the `weather__forecast` tool with latitude and longitude arguments.
- List all available actions from the local device manifest `pump.td.json`.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md