How to Use the timeghost MCP in Pydantic AI

Q: What happens if the timeghost API returns data that doesn't match the schema?

Your agent will raise a ValidationError immediately. This is a core feature, not a bug. It prevents corrupted or unexpected data from propagating through your system, so you can fix the problem at its source.

Bring type-safe time tracking to your Pydantic AI agent. Validate every timeghost API response so your agent never works with bad data.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers — Included with Plan

Connect timeghost MCP to Pydantic AI

Create your Vinkius account to connect timeghost to Pydantic AI — we handle the hosting, security, and runtime updates so you don't have to. No server setup required.

GDPR Included with Plan

Setup timeghost with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity Vinkius runs on Gemini

Gemini

Grok

Build Fail-Safe Reporting

Stop writing defensive code to handle weird API responses. When your agent calls `list_timeghost_entries`, Pydantic AI validates every single entry against your Pydantic model. If the API returns a malformed record, your code will raise a `ValidationError` instantly. This means you can trust your data. Whether you're pulling a list of entries or fetching a single one with `get_timeghost_entry`, you know the data structure is exactly what your application expects. No more silent failures or corrupted reports.

Trust Your Project Data

Your agent can interact with project and task information with total confidence. A call to `get_timeghost_project` or `get_timeghost_task` is automatically parsed and validated. If a field is missing or has the wrong type, your agent knows immediately. This is the power of a schema-first approach. You can even fetch your entire portfolio with `list_timeghost_projects`, and Pydantic AI ensures every object in the list is correct. It eliminates an entire class of bugs related to unexpected API changes.

Validate Every MCP Server Interaction

This isn't just for time entries. Every tool in this MCP server is backed by Pydantic's validation. When your agent checks `list_timeghost_workspaces`, `list_timeghost_clients`, or `list_timeghost_members`, the responses are guaranteed to be clean. You can build reliable administrative agents that manage team structures and client lists without worrying about data integrity. Even a simple `check_timeghost_status` call returns a predictable, validated object. It's about making your agent robust from the ground up.

Setup guide

Set up timeghost MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "timeghost-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to timeghost tools.",
)

result = await agent.run("List recent timeghost transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by timeghost. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect timeghost now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about timeghost MCP in Pydantic AI

Pydantic AI automatically fetches the OpenAPI schema from the MCP server. It then dynamically generates Pydantic models from that schema and uses them to parse and validate every API response at runtime.

Your agent will raise a `ValidationError` immediately. This is a core feature, not a bug. It prevents corrupted or unexpected data from propagating through your system, so you can fix the problem at its source.

Yes, that's a perfect use case. Your agent can fetch records with `list_timeghost_entries`, and because Pydantic AI validates each one, you can be confident that your calculations are based on clean, predictable data structures.

Yes. Pydantic AI works with any LLM. You can use OpenAI, Gemini, Claude, or a local model to power your agent, and the timeghost tool validation will work exactly the same way.

Your data's privacy is maintained at multiple levels. The connection uses your secure Vinkius token, the server is read-only, and it runs in an isolated sandbox. Pydantic AI's validation simply ensures the structure of the data—like time entries and project details—is correct, without storing it.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript