## Summary
- Adds `NetworkTransportError` — a new sibling to `UpstreamError` under
`ToolExecutionError` — for failures where no complete HTTP response was
received from the upstream service (timeouts, connection errors, pool
exhaustion, DNS failures, decoding issues, redirect exhaustion)
- Routes client-construction bugs (`InvalidURL`, `UnsupportedProtocol`,
`MissingSchema`, `SSLError`, `InvalidHeader`, etc.) to existing
`FatalToolError` instead of `UpstreamError`
- Adds 3 new `ErrorKind` values: `NETWORK_TRANSPORT_RUNTIME_TIMEOUT`,
`_UNREACHABLE`, `_UNMAPPED` — operationally distinct telemetry slices
matching the UpstreamError pattern
- `UpstreamError` is unchanged and reserved for real HTTP responses with
status codes
Addresses Eric's feedback on #820: the `include_status_code=False`
post-init null-out workaround is replaced by a clean class hierarchy
where `NetworkTransportError.status_code` is natively `None`.
### Changes
| File | What |
|---|---|
| `arcade-core/errors.py` | 3 new `ErrorKind` values,
`NetworkTransportError` class, `is_network_transport_error` helper |
| `arcade-tdk/providers/http/error_adapter.py` | Full rewrite of httpx +
requests exception routing with 3-way split |
| `arcade-tdk/providers/graphql/error_adapter.py` |
`TransportConnectionFailed`/`TransportProtocolError` →
`NetworkTransportError` |
| `arcade-tdk/errors.py`, `arcade-mcp-server/exceptions.py` | Re-exports
|
| `pyproject.toml` × 3 | Version bumps: core 4.7.0, tdk 3.7.0,
mcp-server 1.20.0 |
| Tests × 3 | 33 new tests, 3 updated (2659 passed, 0 failures) |
### Exception routing table
| Exception | Target | Kind | can_retry |
|---|---|---|---|
| `httpx.HTTPStatusError`, `requests.HTTPError` (with response) |
`UpstreamError` | status-derived | status-derived |
| `httpx.TimeoutException`, `requests.Timeout` | `NetworkTransportError`
| `TIMEOUT` | ✅ |
| `httpx.TransportError`, `requests.ConnectionError` |
`NetworkTransportError` | `UNREACHABLE` | ✅ |
| `httpx.DecodingError`, `TooManyRedirects`, fallback |
`NetworkTransportError` | `UNMAPPED` | varies |
| `httpx.InvalidURL`/`UnsupportedProtocol`/`LocalProtocolError`,
`requests.MissingSchema`/`SSLError`/etc. | `FatalToolError` |
`TOOL_RUNTIME_FATAL` | ❌ |
### Engine companion PR
ArcadeAI/monorepo — `feat/network-transport-error-kinds` adds the 3
`ErrorKind` constants to Go schemas + OpenAPI docs. No engine logic
changes needed (ErrorKind is a string alias, retry uses `can_retry` flag
only, telemetry auto-slices).
## Test plan
- [x] 2659 existing tests pass (0 failures)
- [x] 33 new routing + class tests added
- [x] mypy clean on arcade-core, arcade-tdk
- [ ] Verify engine telemetry dashboard auto-surfaces new
`NETWORK_TRANSPORT_*` kinds after deploy
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> **Medium Risk**
> Changes the error taxonomy and classification helpers used for
retries/telemetry, so misclassification could affect operational
behavior, but the change is additive and covered by new tests.
>
> **Overview**
> Adds a new error category for outbound request failures that never
yield a complete upstream response: `NetworkTransportError` (sibling to
`UpstreamError`) plus
`ErrorKind.NETWORK_TRANSPORT_RUNTIME_{TIMEOUT,UNREACHABLE,UNMAPPED}` and
matching `is_network_transport_error` classification helpers on both
`ToolkitError` and the wire-model `ToolCallError`.
>
> Re-exports `NetworkTransportError` from `arcade-tdk` and
`arcade-mcp-server`, bumps package versions (`arcade-core` 4.7.0,
`arcade-tdk` 3.7.0, `arcade-mcp-server` 1.20.0) and dependency minimums,
and expands `core/test_errors.py` to cover the new kind
invariants/defaults and classification behavior.
>
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
d2b89078729c6a67ba42684dc98445352238bc1d. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Versions:
* arcade-mcp\==1.0.0rc1
* arcade-mcp-server\==1.0.0rc1
* arcade-core\==2.5.0rc1
* arcade-tdk\==2.6.0rc1
* arcade-serve\==2.2.0rc1
### Summary
Adds first-class MCP support across Arcade, introduces a new MCP server
and CLI, unifies the project under the arcade-mcp name, overhauls
templates/scaffolding, and improves developer tooling, secrets
management, and examples.
### Highlights
- **MCP Server & Core**
- New MCP server with stdio and HTTP/SSE transports, session management,
resumability, and lifecycle handling.
- FastAPI-like `MCPApp` for building servers with lazy init; integrated
worker+MCP HTTP app option.
- Middleware system (logging and error handling), robust exception
hierarchy, and Pydantic-based settings.
- Async-safe managers for tools, resources, and prompts backed by
registries and locks.
- Developer-facing, transport-agnostic runtime context interfaces (logs,
tools, prompts, resources, sampling, UI, notifications).
- Conversion from Arcade ToolDefinition to MCP tool schema; OpenAI JSON
tool schema converter.
- Parser supports `@app.tool`/`@app.tool(...)` decorators.
- **CLI**
- New `mcp` command to run MCP servers with stdio or HTTP/SSE.
- New `secret` command to set/list/unset tool secrets (supports .env
input, preserves original casing for lookups).
- `new` command refactored; option to create a full toolkit package with
scaffolding.
- `chat` command removed.
- `serve.py` imports updated to `arcade_serve.fastapi.telemetry`;
version retrieval now uses `arcade-mcp`.
- `show.py` refactor to use new local catalog utilities.
- `display_tool_details` improved: adds “Default” column and handles
nested properties.
- **Configuration & Discovery**
- New `configure.py` to set up Claude Desktop, Cursor, and VS Code to
connect to local or Arcade Cloud MCP servers.
- Discovery utilities to find/install toolkits, build `ToolCatalog`s,
analyze files for tools, load kits from directories (pyproject parsing),
and build minimal toolkits.
- Better handling of provider API key resolution and evaluation suite
loading.
- **Templates & Scaffolding**
- Reorganized template structure (minimal vs full); moved
`.pre-commit-config.yaml`, `.ruff.toml`, license, Makefile, README,
tests, and tools layout to correct paths.
- Minimal template adds `.env.example` for runtime secret injection.
- Template pyproject updated for MCP servers; includes sample server
with greeting and secret-reveal tools.
- Authorization flow in templates simplified.
- **Repo-wide Renaming & Examples**
- Migrates references from `arcade-ai` to `arcade-mcp` across READMEs,
scripts, and package metadata.
- Examples updated (LangChain/LangGraph/AI SDK/TypeScript) and package
name changed to `arcade-mcp-sdk`.
- **Evals & Core Utilities**
- Evals now use OpenAI tooling format (`OpenAIToolList`, `to_openai`);
`tool_eval` takes `provider_api_key`.
- Core utilities: fixed `does_function_return_value` by dedenting before
parse; version bump to `2.5.0rc1` and dependency cleanup.
- **Tooling & CI**
- `setup-uv-env` action splits toolkit vs contrib dependency
installation.
- Pre-commit: excludes `libs/arcade-mcp-server/mkdocs.yml` and
`libs/tests/` from YAML and Ruff hooks; Ruff per-file ignores (e.g.,
C901 in `libs/**/*.py`, TRY400 in server docs paths).
- Makefile updates for uv env setup, quality checks, tests, builds, and
new `shell` target.
- Added Makefile to MCP server library to streamline dev workflow.
- **Cleanup**
- Removed `claude.json` config.
- Simplified stdio entrypoint; removed unused imports (`arcade_gmail`,
`arcade_search`).
### Breaking Changes
- **CLI**: `chat` command removed; use `mcp`, `secret`, and updated
`new`.
- **Naming**: All users should update references from `arcade-ai` to
`arcade-mcp`.
- **Templates**: File paths moved; downstream scripts referencing old
template locations may need updates.
### Getting Started
- Run an MCP server:
- `arcade mcp --stdio --toolkits your_toolkit`
- `arcade mcp --http --toolkits your_toolkit`
- Manage secrets:
- `arcade secret set your_toolkit KEY=value`
- `arcade secret list your_toolkit`
- `arcade secret unset your_toolkit KEY`
- Configure clients:
- `arcade configure` to set up Claude Desktop, Cursor, and VS Code for
local/Arcade Cloud MCP.
---------
Co-authored-by: Sam Partee <sam@arcade-ai.com>
Co-authored-by: Shub <125150494+shubcodes@users.noreply.github.com>
Francisco Or Something