0
mtpx
multi tool protocol
pip install mtpx
docs / runtime / sdk

Project Direction

Project Direction explains the roadmap layer of MTPX with practical guidance for building inspectable, tool-using agents.

Pr
Project Direction
Chapter 013PlanningRoadmapIndex
01Orientation

Project Direction belongs to the planning track. The page breaks the idea into responsibilities, implementation rules, failure modes, and the signals you should expose in a product UI.

Use this when

Use this when you need to understand how project direction affects a real MTPX agent before you wire it into an application.

  • What project direction owns in the runtime.
  • How it connects to planning, tool execution, events, providers, or storage.
  • What to log, test, and expose to users when this layer is active.
  • Common mistakes that make agent systems hard to inspect.
02 / minimal pattern
from mtp import Agent
from mtp.providers import Groq

agent = Agent.MTPAgent(provider=Groq(), tools=tools)
print(agent.run("Project Direction: explain the next runtime step.", max_rounds=4))
03 / manual

Read the system

The complete source manual—syntax, examples, linked references, edge cases, and implementation notes.

Documentation index ↗
01TL;DR

This document is the canonical direction for this repository. If other docs conflict with this file, this file should be treated as the source of truth.

TL;DR

This repo contains two related but different things:

  1. MTP Protocol
  • A protocol model for tool orchestration (tool schemas, calls, plans, dependencies, policy, execution semantics).
  • This is the core "Model Tools Protocol" idea.
  1. MTP Agent SDK
  • A Python framework that uses MTP protocol primitives to build production agents.
  • Includes providers, toolkits, storage, transport, events, and higher-level agent APIs.

MCP is important, but it is not the product identity. MCP interoperability is a capability of this SDK, not the definition of MTP.

02Product identity

Product identity

MTP is the primary product and protocol identity.

MTP Agent SDK is the implementation layer around the protocol.

MCP is an interoperability target and integration surface.

Think of the architecture like this:

  • MTP protocol: what gets modeled and executed.
  • MTP SDK: how developers build apps with that model.
  • MCP adapter/transports: how MTP can communicate with MCP ecosystems.
03What we are building

What we are building

We are building a protocol-first agent system that is:

  • More than an MCP wrapper.
  • More than a provider SDK.
  • More than just an agent loop.

It combines:

  • protocol semantics (mtp.protocol, mtp.schema)
  • deterministic runtime (mtp.runtime)
  • agent orchestration (mtp.agent, mtp.simple_agent)
  • provider adapters (mtp.providers)
  • tool ecosystem (mtp.toolkits, mtp.tools)
  • persistence (mtp.session_store)
  • transports (mtp.transport, mtp.mcp_transport)
  • observability and events (mtp.events)
04Design principles

Design principles

  1. Protocol-first, framework-enabled
  • Protocol contracts should stay explicit and stable.
  • Framework features should build on protocol contracts, not bypass them.
  1. Interoperability without identity loss
  • MCP compatibility should be first-class.
  • But MTP should not be reduced to "MCP adapter only."
  1. Clear layer boundaries
  • Runtime executes plans/tools.
  • Agent orchestrates provider/runtime loops.
  • Providers translate model APIs into agent actions.
  • Toolkits define capability implementations.
  • Transports move envelopes/messages only.
  1. Practical production focus
  • cancellation semantics
  • policy controls
  • session persistence
  • streaming/events
  • auth extensibility
05Scope boundaries (important

Scope boundaries (important for contributors)

In scope

  • Evolving MTP protocol entities and semantics.
  • Improving SDK ergonomics and reliability.
  • Strengthening provider parity and toolkit quality.
  • MCP interoperability and transport quality.
  • Observability and operational safety.
06Out of scope

Out of scope

  • Rebranding MTP as "just MCP."
  • Adding provider-specific shortcuts that bypass runtime semantics.
  • Coupling protocol design to one provider or one transport.
07MCP relationship (exact stan

MCP relationship (exact stance)

MCP support is intentional and strategic:

  • MTP supports MCP method surfaces for interoperability.
  • MTP includes dedicated MCP transports.
  • MTP includes MCP auth/cancellation/progress support.

But:

  • MTP protocol remains a first-class protocol model.
  • SDK features that are beyond MCP baseline (for example strict dependency enforcement, dynamic tool mutation, output refinement, orchestration mode) remain part of MTP's value.
08Near-term implementation dir

Near-term implementation direction

Priority areas for next contributors:

  1. Provider capability parity matrix and consistent behavior guarantees.
  2. Transport maturity (resumability, streaming robustness).
  3. Session analytics/tracing APIs.
  4. CLI/project scaffolding (mtp new).
  5. External conformance matrix (including MCP clients).
09Naming and messaging guideli

Naming and messaging guidelines

Use these terms consistently in docs and PRs:

  • "MTP protocol" for protocol-layer concepts.
  • "MTP Agent SDK" for framework/runtime/tooling layer.
  • "MCP interoperability" for adapter/transport compatibility.

Avoid phrasing like:

  • "MTP is MCP"
  • "MTP is only an MCP adapter"

Preferred phrasing:

  • "MTP is protocol-first and MCP-compatible."
  • "MTP SDK includes MCP interoperability as one integration surface."
10Contributor checklist for ne

Contributor checklist for new features

When implementing a feature, verify:

  1. Which layer does this belong to: protocol, runtime, agent, provider, toolkit, transport, or MCP adapter?
  2. Does it preserve existing layer boundaries?
  3. Does it improve MTP directly, or only MCP integration?
  4. Is documentation updated in:
  • this file (PROJECT_DIRECTION.md) if direction changes,
  • ARCHITECTURE.md for structure,
  • ROADMAP.md for status,
  • topic docs for usage examples.
11Final statement

Final statement

We are building:

  • MTP as a protocol and execution model,
  • MTP Agent SDK as a practical developer framework,
  • with MCP compatibility as a major interoperability feature.

That is the intended direction of this project.

01

Read

Understand where Project Direction sits in the agent loop before adding abstractions.

02

Wire

Connect the smallest useful provider, registry, store, or event stream first.

03

Observe

Expose events, logs, results, and failure states while the runtime is still moving.

04

Harden

Add policy, tests, retries, and audit traces after the behavior is visible.

Next docMTP Protocol Spec