Build a Claude Connector: A Practical Starting Point

Building a custom connector for Claude means building an MCP server. MCP (a standard way for an AI app to call an outside tool) defines how a Claude client discovers and calls external tools, so a correctly implemented MCP server lets Claude query any data source or service you expose. fenbs can hold the integration requirements, design decisions, and verification tasks for the build so any assistant on your team can pick up where the last session left off.

You do not need to build a connector from scratch for most popular services. Check whether a maintained MCP server already exists before starting. If one does, evaluate it; if none fits your needs, build your own.

What an MCP server is and how Claude uses it

An MCP server is a process that exposes a set of named tools to a connected Claude client. When you add a server to your Claude client configuration, Claude can call those tools by name during a session. The server handles authentication, data fetching, and formatting, then returns the result for Claude to use in its response.

The MCP protocol supports two transport types: stdio for a local subprocess and HTTP with Server-Sent Events for a remote server. A local server is simpler to build and deploy; a remote server can serve multiple clients and is required if the tool needs to run without the user's machine being on.

Deciding what your connector needs to do

Before writing any code, define the tools your MCP server will expose. A tool is a function with a name, a description, and a schema for its inputs. Claude uses the description to decide when to call the tool. Write descriptions that are specific enough for Claude to pick the right tool but concise enough to stay inside the context budget.

• What data source does the connector need to access? A database, a REST API, a file system, or a third-party service?
• What specific operations does a Claude session need? Read, search, create, or update?
• What is the minimum permission scope required for each operation?
• What should the server never expose? Personal data, credentials, and broad administrative access belong outside the tool boundary.

A connector that does one thing well is easier to trust and easier to debug than one that tries to do everything. Start with a single read operation before adding writes or complex queries.

Authentication and access boundaries

Authentication is the most important design decision in an MCP server. The server must authenticate with the data source on behalf of the user, and it must not expose those credentials to Claude or log them anywhere accessible.

For services that support OAuth 2.0, implement an OAuth flow and store only the token, never the user's raw password. For services that use API keys, pass them as environment variables to the server process, not as hardcoded strings in the source. Review the data source's terms of service to confirm that programmatic access is permitted for your intended use.

Scope the access token to the minimum permissions the tool needs. A search tool needs read access; it does not need write or delete. Request only what is necessary and document what you requested and why.

The MCP server structure

An MCP server implementation typically includes: a server object that registers the available tools, a handler for each tool that performs the data operation, and transport setup for how the server communicates with the client. The MCP SDKs for TypeScript and Python provide the scaffolding; your job is to implement the tool handlers.

server.tool(
  "search_documents",
  "Search documents in the connected store by keyword.",
  { query: z.string() },
  async ({ query }) => {
    const results = await dataSource.search(query);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  }
);

Keep tool outputs focused. Return the data Claude needs to answer the user's question, not the full API response. Large outputs eat context window and make it harder for Claude to identify the relevant part.

See Claude connectors explained for how the client-server relationship works. The Claude connectors create guide covers Anthropic's connector submission process if you want to publish a connector officially.

Testing before you connect

Test the MCP server in isolation before connecting it to Claude. Send it a tool call directly and check that the response has the right structure, that authentication works with a real token, and that the error handling is clear when a query fails or a record is not found.

Then connect it to a Claude client with a test account and verify that Claude can discover and call the tool correctly. Check that Claude's description-based tool selection works as intended: does Claude call the right tool for the right question?

Common mistakes to avoid

• Returning too much data per tool call. Trim the response to what Claude needs.
• Vague tool descriptions. Claude uses the description to decide when to call the tool; be specific.
• Storing API credentials in source code. Use environment variables.
• Requesting broader access than necessary. Scope to the minimum required.
• Skipping error handling. A tool that returns an unformatted stack trace on failure is hard for Claude to interpret.

How to do this with fenbs

1. Create a free account at fenbs. Add a project for the connector build.
2. Write the tool names, descriptions, and input schemas as tasks with their requirements as the task description.
3. Record each design decision, such as the chosen authentication method and the access scope, as a Decision in the project.
4. Add verification steps as tasks: test authentication, test each tool handler, test the client connection.
5. Connect Claude Code over MCP from Integrations so it reads the requirements and decisions before each coding session.

fenbs keeps the build requirements and decisions outside any one session. When a different assistant or a new conversation takes over, it reads the same agreed design before continuing. For connector creation through Anthropic's official process, see Claude connectors create.