The filesystem server stopped working with the OpenAI Agent SDK.

Describe the bug
It has been working with an old version of the filesystem server. However, after upgrading the server, openAI (and also the model context protocol inspector) throw errors when trying to list the tools.

To Reproduce
Either:

use npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ./
try to "list tools"
get the following error:

[
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      0,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      1,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      2,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      3,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      4,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      5,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      6,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      7,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      8,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      9,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      10,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      11,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  },
  {
    "code": "invalid_literal",
    "expected": "object",
    "path": [
      "tools",
      12,
      "inputSchema",
      "type"
    ],
    "message": "Invalid literal value, expected \"object\""
  }
]

Or:

use openai sdk to start the MCP server
when trying to interact with it
get the following error:

openai.BadRequestError: Error code: 400 - {'error': {'message': 'Invalid schema for function \'read_file\': schema must be a JSON Schema of \'type: "object"\', got \'type: "None"\'.', 'type': 'invalid_request_error', 'param': 'tools[0].parameters', 'code': 'invalid_function_parameters'}}

Expected behavior
The MCP server should work :)

Logs
Provided in the steps to reproduce

Additional context
Currently uses:
node 24
openai sdk 0.6.1
filesystem server latest

I try to find out in which version this happened. But it seems to be an issue deeply hidden. The published versions do not have this issue and when I download the main branch and run it, it works until the result is parsed where openAI agent sdk throws a different error about return types.

Addition: apparently it is a combination of several factors. The upgrade of "zod" and the upgrade of the MCP SDK.

Zod4 breaks somehow, and using zod3 with the "registerTool" method of the SDK also breaks.

Current working version for me:

  "dependencies": {
    "@modelcontextprotocol/sdk": "^1",
    "zod": "^3"
  }

and inside the mcp server use server.tool instead of server.registerTool. With this, I can run the server without issues.

finally got it working. but not with zod4. there is some issue with zod4 and the sdk I guess.

@buehler

@buehler , do you happen to know which version it broke for? Even as I start navigating backwards via npx -y @modelcontextprotocol/inspector@0.16.8 npx @modelcontextprotocol/server-filesystem@2025.1.14 ./data it is still failing for me?

@domdomegg

cc @domdomegg - looks like there was an issue with the filesystem refactor, I started looking into it but if you get a chance wanted to make sure you saw this too.

i get the same issue

@vincentjames501

Hey @vincentjames501, I think it is more related to zod and the mcp-sdk. I did go back in time and installed all versions of the fileserver and somehow no version worked.

I tried around with sdk / zod versions locally and managed to get an implmementation running:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { readFile } from 'fs/promises';
import { z } from 'zod';

const log = (...params) => console.error(...params);

const server = new McpServer({
  name: 'filesystemserver',
  version: '1.0.0',
  capabilities: {
    resources: {},
    tools: {},
  },
});

server.registerTool(
  'read_file',
  {
    title: 'Read File',
    description: 'Read the content of a file and return it as text.',
    inputSchema: {
      path: z.string(),
    },
    outputSchema: {
      content: z.string().nullable(),
      error: z.string().optional(),
    },
  },
  async ({ path }) => {
    try {
      log('Reading file at path:', path);
      const content = (await readFile(path)).toString('utf8');
      return {
        content: [],
        structuredContent: {
          content,
        },
      };
    } catch (e) {
      log('Error reading file:', e);
      return {
        content: [],
        structuredContent: {
          content: null,
          error: `${e}`,
        },
      };
    }
  }
);

package json:

{
  "name": "filesystem_mcp_server",
  "private": true,
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1",
    "zod": "^3"
  }
}

So finally, I think it may not be related to the code of fileserver, but more to the SDK in combination with Zod.

EDIT: note that this code does work with the openAI agent sdk, HOWEVER: you need to set use_structured_content=True in the MCPServerStdio class when instantiating the mcp server.

The latest main branch source code no longer has this issue. It appears to have been fixed in recent commits, but the npm package has not been updated yet.

In the August 23rd version, the "inputSchema" was generated via the zodToJsonSchema method from "zod-to-json-schema" package. However, it appears this method was used incorrectly, resulting in all tool‘s "inputSchemas" being {"$schema":"http://json-schema.org/draft-07/schema#"}. and failed validation by the MCP SDK.

Thanks all for the sleuthing, it does seem like the issue is that this hasn't been published to npm in a while. Will update here once that gets sorted out.

it does seem like the issue is that this hasn't been published to npm in a while

Is that the filesystem server, or the OpenAI / inspector? I can try to chase around internally to get the filesystem server release approved.

@domdomegg

@domdomegg its the filesystem server: https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem

Looks like this is the latest release awaiting approval: https://github.com/modelcontextprotocol/servers/actions/runs/19665766137

Okay I managed to get approval, and sort out the NPM token being expired (#3061).

The filesystem server has been published to NPM: https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem

Although I think this isn't solved by the release, and the same issue persists if you have a later zod version installed. Root cause might be modelcontextprotocol/typescript-sdk#1028

And underlying that is modelcontextprotocol/typescript-sdk#555. I think the solution might be to use https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/1.23.0-beta.0 which has backwards-compatible support for Zod 4.

I think #3065 + another release should fix this

1.23.0 works. But have another error "keyValidator._parse is not a function"

1.23.0 works. But have another error "keyValidator._parse is not a function"

same issue

1.23.0 works. But have another error "keyValidator._parse is not a function"

try npm cache clean --force

1.23.0 works. But have another error "keyValidator._parse is not a function"

1.23.0 works. But have another error "keyValidator._parse is not a function"

same issue

Run npm config get cache to obtain the cache folder path. Then navigate to the “_npx” folder within the cache directory, locate the folder corresponding to “filesystem”, and delete it. This worked for me.

It seems the latest version returns an incorrect input schema (the above image shows the "properties" is empty).

Unvalidate claim:
Not typescript-sdk expert, but the code doesn't look right, for example

server.registerTool(
  "move_file",
  {
    title: "Move File",
    description:
      "Move or rename files and directories. Can move files between directories " +
      "and rename them in a single operation. If the destination exists, the " +
      "operation will fail. Works across different directories and can be used " +
      "for simple renaming within the same directory. Both source and destination must be within allowed directories.",
    inputSchema: {
      source: z.string(),
      destination: z.string()
    },
    outputSchema: { content: z.string() },
    annotations: { readOnlyHint: false, idempotentHint: false, destructiveHint: false }
  },
  async (args: z.infer<typeof MoveFileArgsSchema>) => {
    const validSourcePath = await validatePath(args.source);
    const validDestPath = await validatePath(args.destination);
    await fs.rename(validSourcePath, validDestPath);
    const text = `Successfully moved ${args.source} to ${args.destination}`;
    const contentBlock = { type: "text" as const, text };
    return {
      content: [contentBlock],
      structuredContent: { content: [contentBlock] }
    };
  }
);

Shouldn't the inputSchema just reuse MoveFileArgsSchema? , which also has z.object

Worth checking the Inspector against the OpenAI Agent SDK side-by-side. The filesystem server's tool list response shape changed between protocol versions, and OpenAI Agent SDK is stricter about that than the Inspector.

Specifically: the inputSchema field name and casing changed in one of the protocol bumps. If the OpenAI SDK is raising on a field that the server is now emitting in a different shape, that's the mismatch.

A protocol-version-pin in the OpenAI SDK side might unblock the regression while the server adapts.

Interesting issue. We've been working with MCP server orchestration in our project (AI Workdeck — an AI workspace for legal document workflows), and we've encountered similar compatibility issues between MCP servers and different agent SDKs.

One thing that helped us was ensuring the MCP server properly implements the protocol handshake with explicit capability negotiation, rather than assuming a specific client behavior. The OpenAI Agent SDK may be stricter about the initialization sequence compared to Claude Desktop.

If the issue is specifically with Windows path handling, it might be worth checking how the server normalizes paths during the tools/call response — we found that some path formats that work with one client SDK may fail with others due to different URI handling.

Would be great to see this fixed — interoperability between MCP servers and multiple agent SDKs is critical for the ecosystem.

Closing: superseded by the v2 release.

Thank you for reporting this, and apologies for the long wait for a response.

Since this was filed, the reference servers have been rebuilt for the 2026-07-28 MCP specification (#4857) and released as v2 (2.0.0 on npm for the TypeScript servers, 2026.10.19 on PyPI for the Python servers). Each server now runs on v2 of its SDK, and the behavior described here has either been fixed or no longer exists in the same form. The zod 4 / SDK v1 schema-conversion problem that produced non-object inputSchema types is gone: v2/main builds each tool's input schema as JSON Schema on SDK v2.

This is not a judgment on whether the problem was real; it's a consequence of the code it describes having been replaced. This is happening as part of the backlog triage in #4875.

If this still happens on the v2 release, we'd genuinely like to know. Please open a fresh issue with the version you're running and steps to reproduce, and we'll look at it. Note that this repository accepts contributions as issues rather than pull requests; see CONTRIBUTING.md.

Thanks for taking the time to report it.

Navigation Menu

Repository navigation

The filesystem server stopped working with the OpenAI Agent SDK. #3051

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

The filesystem server stopped working with the OpenAI Agent SDK. #3051

Description

Activity

buehler commented on Nov 24, 2025

buehler commented on Nov 24, 2025

buehler commented on Nov 24, 2025

vincentjames501 commented on Nov 24, 2025

olaservo commented on Nov 25, 2025

badspider7 commented on Nov 25, 2025

buehler commented on Nov 25, 2025

Wo1framalpha commented on Nov 25, 2025

Wo1framalpha commented on Nov 25, 2025

olaservo commented on Nov 25, 2025

domdomegg commented on Nov 25, 2025

olaservo commented on Nov 25, 2025

domdomegg commented on Nov 25, 2025

domdomegg commented on Nov 25, 2025

domdomegg commented on Nov 25, 2025

domdomegg commented on Nov 25, 2025

mattjin commented on Nov 26, 2025

jshi0929 commented on Nov 26, 2025

badspider7 commented on Nov 26, 2025

Wo1framalpha commented on Nov 26, 2025

quangIO commented on Nov 26, 2025

MukundaKatta commented on May 10, 2026

zeweihan commented on Jun 4, 2026

cliffhall commented on Oct 19, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions