Forem: Kyle Mistele

MCP Deep Dive: the Great, the Broken, and the Downright Dangerous

Kyle Mistele — Wed, 09 Jul 2025 15:13:27 +0000

Introduction

MCP's vision began with a great idea: a universal standard to connect AI models with arbitary tools and capabilities in a seamless, plug-and-play way. It's a fantastic vision, and as a result, a lot of people are very excited about MCP.
The vision is evident in its specification, and the appeal of it is evident in the truly enormous number of MCP servers that people built nearly overnight once MCP was released, and in the great deal of writing about it.

However, once we move past that lofty vision, we descend into the (presently) broken reality, where poor design decisions and broken implementations abound, and where some serious security problems lay hidden.

As someone who has spent recent months deep in the trenches building with MCP, I'm familiar with what's great about MCP, what's broken, and what's downright dangerous. This is my report from the front lines.

The Good: A Visionary Specification with Untapped Potential

On paper, the MCP specification is impressive. It provides a rich, universal framework for connecting AI models to tools, data, and services. The most well-known primitive is tools, but the spec offers so much more:

Resources: For structured data access (e.g., connecting to a database).
Prompts: For providing specific context to a model.
Roots: For anchoring a model's operational context.
Sampling: An awesome primitive that could enable advanced use-cases like bidirectional communication between a model and a tool.
Authorization: Integrating an MCP server with an upstream OAuth authorization server allows a user to authorize an agent to take actions on his or her behalf with 3rd-party apps and services.

The spec also defines multiple different transports that provide optionality in how to use and deploy MCP. These primitives offer a powerful, holistic way to build sophisticated AI-powered applications.

And lots of great things have been built with MCP! I use Puppeteer's MCP server to enable faster testing and iteration of UIs in my Cursor agent, and Supabase/Postgres MCP servers to give my agent database access, and a number of other things.

So much cool stuff has been built! But unfortunately, so much of the specification's potential remains largely untapped.

The Broken: Where Implementations Fall Short, and the Spec Fails

This is where the promise of MCP meets a harsh reality of incompleteness. Many parts of the MCP ecosystem are broken, either through incomplete implementation or because the specification itself is flawed.

1. MCP Implementers Only Support Tools

Most MCP hosts like Cursor and Windsurf only implement the tools primitive of MCP, and choose not to support resources, roots, prompts, and/or sampling.

Why?

Universality. Tools are the most straightforward primitive.

Opinionation & Compatibility: A primary critique of MCP which it released was that it seemed to be opinionated in favor of Anthropic's models. Apart from the Claude family of models, most models don't have a good way to model any of the MCP primitives apart from tools. So most MCP hosts apart from Anthropic-specific ones like Claude desktop stick to just tools because they are portable to non-Anthropic models in a comparatively easy manner. Other primitives would require special handling or additinoal abstractions and complexity.

Workarounds: Resources can often be crudely implemented as tools, so implementers don't bother with a proper implementation.
This is a broken practice. Many things currently modeled as tools, like database connectors, should really be resources. By ignoring the other primitives, the ecosystem is limiting MCP's power to its lowest common denominator.

Security and additional considerations: Since sampling allows the MCP server to prompt the agent it's connected to, there are
security and trust considerations about if/how to allow this. Do you just let the LLM use the tools from the MCP server that's doing the sampling, or all tools that are plugged into the agent? The latter would enable much more powerful functionality, but also introduces worse risks for a rogue MCP server.(As I'll discuss later though, you should treat MCP servers like code — if you can't trust it 100%, you shouldn't run it).

So ultimately the decision to primarily support the tools primitive is understandable, while regrettable — it's the only one
that's truly portable and model-agnostic.

2. The Transport Layer Mess

MCP's transport options are a mixed bad. Between inconsistent feature support, blurred lines, and unsuitability for production use-cases,
it can be hard for implementers to choose the right transport the newer Streamable HTTP transport, which is optionally stateless, is really great!

STDIO works well for local apps like Cursor & Windsurf, but is not well-suited for production.

To use an MCP server that uses the STDIO transport, you launch another process with npx, bunx, uv/uvx or something simliar, and then MCP JSON-RPC messages are sent into the process via STDIN, and received via STDOUT. This works well for applications running locally on your host, but there are a number of problems for deploying this as an application:

Hidden Dependencies: MCP servers often rely on tools & toolchains like npx, uv, docker, etc. to install and run the MCP server's source code and dependencies. These dependencies are not tracked in your project's version control, and may not be installed in your deployment environment (if they're installable at all, e.g. with Vercel's platform)
Long-Lived Stateful Connections: STDIO servers require a long-lived stateful connection between the MCP client and the server. This doesn't work for serverless deployment platforms that use short-lived functions like AWS Lambda, Vercel, and certain cloudflare products.
Poor Scaling Properties: For each agent loop/thread/instance that you have that needs to use the MCP server, you need an entirely separate instance of the MCP server in a new process. This means that the number of processes you have to run scales linearly with the number of agents that you have. These processes can use up system resources, especially memory. In an idea world, you'd want one server instance to be able to serve multiple different agent instances.
Feature incomplete-ness: STDIO MCP servers are not compatible with the OAuth portion of the MCP Specification; to do so you must use an MCP bridge/proxy like mcp-remote. This may not seem like a big problem right now, but lack of feature parity between transports makes transports less transparent to applications and makes the protocol more difficult to maintain.

Similar problems obtain with SSE.

Hidden Dependencies: Similar to STDIO, this is a problem with SSE too. Especially for remote SSE servers.
Long-lived stateful connections: Similar to STDIO, SSE requires long-lived stateful connections that are unsuitable for serverless environments.
Poor Scaling Properties: SSE does not multiplex multiple clients to a single server, so you must have a unique SSE instance for each agent instance. This is additionally a problem because SSE binds to a port, so you must either use different ports and implement a discovery mechanism, or implement a proxy that handles session tracking and routing.
Unclear best practices: Unlike STDIO, SSE can be used for both local and remote MCP servers. It supports OAuth, but is more commonly used with API keys, session tokens, or bearer tokens. How to handle initiating multiple SSE servers and port binding with proxies, and authorization and routing are all open questions; deploying SSE to production for both production and local use-cases requires implementing solutions to this that are not part of the specification and for which best practices do not exist.

Streamable HTTP is the right way forward, but still has problems.
The streamable HTTP transport fixes a lot of the problems with STDIO and SSE. It's optionally stateless by specification, which means that
individual MCP servers can elect to implement streaming, or just a shorter-lived request/response pattern. It's up to clients to roll with whatever the server chooses, though — there's no negotiation (which is fine imho, just worth nothing).

The streamable HTTP transport also supports OAuth, which is a big win. But there are still a few major drawbacks:

Despite being adopted months ago, most popular MCP hosts still don't support this transport. As a result, most servers don't support it.
Unlike the STDIO and SSE transports, streamable HTTP servers do not separate the transport from the server in the same way. The user must write a web app which properly consumes/implements the transport, and which calls the MCP server when appropriate. Reference implementations exist in the documentation, but this is a pain for people who want to write a server once and then deploy it with arbitrary transports.

3. The OAuth Debacle

MCP supports OAuth, yay! Unfortunately, this is a place where both the specification and the implementation of the specification are bad. Adding OAuth to MCP was 100% the right idea, but the execution was frankly poor. Why?

The specification incorrectly mandates than an MCP server should behave both as an OAuth authorization server, and as an OAuth resource server.

As Jared Hanson, the creator of Passport JS, founder of Keycard Labs, and author of most OAuth-Related JavaScript code on the internet observed in the MCP OAuth RFC, the proposed (and later accepted) RFC has an incorrect model and implementation of the protocol.

This is poor from a protocol design standpoint, this is poor from a security standpoint, this is bad from a compatibility standpoint, and this is bad from a server builder's standpoint. The decision to model MCP this way seems to have been made out of convenience and ease-of-implementation concerns rather than longer-term concerns.

For what it's worth, the MCP specification relies on several OAuth extensions
including the rarely-used RFC7591 Dynamic Client Registration Protocol to facilitate on-the-fly client registration with the MCP server since it behaves as an authorization server,
as well as the (relatively) new RFC9728 Protected Resource Metadata standard.

Okay, but why is this a problem?

I'm so glad you asked.

First, OAuth-enabled MCP server implementers now have to either (a) implement all of these OAuth capabilities into their MCP servers, or
(b) have to _proxy all OAuth-related requests to an upstream OAuth authorization server. Both of these are exceptionally bad options.

MCP server developers should not have to implement OAuth and multiple rarely-used OAuth extensions to ship a streamable HTTP server that supports OAuth. To suggest otherwise is frankly ridiculous
The reference code is incomplete and broken. When I implemented the second Streamable HTTP- and OAuth-compatible MCP server to exist, I had to subclass and re-implement multiple parts of OAuth-related functionality due to broken dynamic client registration, hard-coded URLs, and proxy logic that will not work for 99% of OAuth authorization server providers due to lack of support for the Dynamic Client registration OAuth extension which MCP relies on.
The approach recommended by the docs and reference code, of proxying to an upstream OAuth provider, has several security concerns that are not described in the docs, and which implementers would not know to provide for. I will write more on this below.

Second, A core principle of OAuth is the separation of concerns. This design is not just wrong; it's a known security anti-pattern.

Furthermore, the specification's reliance on Dynamic Client Registration was a terrible decision. Almost no major OAuth providers (Google, GitHub, etc.) support it out of the box. Auth0 supports it, but requires you enable it since it's not enabled by default. The ability to do this is buried deep in settings menus, and your dashboard and tenant get incredibly messy (and messed-up) if you enable it since Auth0 does not intend for this use-case.

This means that to build a compliant MCP server, even if you implement a proxy to an upstream OAuth provider, in most cases you will still have to implement some type of wrapper to support Dynamic Client Registration and other parts of OAuth yourself just to proxy to an upstream provider.

As I mentioned above, this isn't theoretical — I had to rewrite broken OAuth code in the official TypeScript MCP SDK to get my server working correctly.

The Dangerous: A Pragmatic Guide to MCP Security

Remote Code Exection on your Host

With all the talk about MCP security (some of which is motivated by opportunistic security vendors), you might think that MCP requires a complex new threat or risk model. It doesn't, at least for local servers. The trust model is simple: MCP should be treated exactly like any other third party code dependency.

Here's how you should think about it:

Local MCP Servers (STDIO & SSE): Treat any MCP server you install and run locally the same way that you would an npm or PyPi package. They are arbitrary code. If you don't trust the author and the distribution source, don't download and run it. It's that simple. A malicious local MCP server could execute arbitrary code, or prompt-inject your LLM.
Remote MCP Servers (SSE, Streamable HTTP): Treat any remote MCP server just like any untrusted software. If you don't trust the author and/or domain, do not connect to the server or send it credentials. In a sense, you should actually also treat it as local MCP server in that you should treat it as untrusted code - since in addition to stealing credentials, a rogue remote MCP server could easily trick your coding agent into writing and executing malicious code.

While the specific implementations of the attack (arbitary code execution by malicious software) differ slightly for remote MCP servers in that they are remote apps that can cause code execution on your local device, the model you should have for both is simple. Do not blindly trust code that you didn't write.

OAuth-related security flaws

Having said that, there are other issues that can (and commonly do) arise in MCP servers' implementation of the OAuth part of the MCP specification for remote MCP servers that you need to be aware of:

Access token issuance when using MCPs as proxies for upstream OAuth Authorization servers.

As noted, if you are proxying an MCP server's authorization logic to an upstream Authorization server, you may be tempted to return the access token from the upstream authorization server to the downstream client. You should not do this; rather you should verify the access token from the server, and then issue a sort of "proxy token" to the client, which the client can then to use with your MCP server, and upon verification when necessary, your MCP server can make authorized requests to resource servers with the actual access token from the authorization server.

Exposing the access token from the upstream authorization server to the downstream client can allow a compromised or malicious client
to access resources with upstream resource servers in undesired ways, especially if the issued access token has over-permissive scopes. Issuing a sort of "proxy access token" to the client, and ensuring that the only time that the real access token is used is in requests from your MCP server to the correct resource servers, prevents this attack.

Phishing attacks by malicious MCP servers

Regrettably, I can't share a lot about this attack right now since it's a severe issue in the current protocol revision (2025-06-18) that is (a) unpatched, and (b) trivially exploitable. You should think of this is a High- or Critical-severity CVE issue involving credential theft.

I was initially going to write about this in more detail, but all information about it has been stripped from the public GitHub threads & discussions, and numerous tweets about it have been deleted. I didn't get the memo directly, but this indicates that the protocol maintainers are not ready for the specifics of this issue to
be made public until it can be remediated, so I have elected to not share specifics at this time.

Conclusion: A Plea for Refinement

My journey with MCP reveals a protocol that has a great vision, but a flawed execution. To move forward, the community needs to:

Clean up the transport mess: Deprecate the SSE transport in favor of streamable HTTP transport; support OAuth in the STDIO transport, and provide clear recommendations about when it is (and is not) appropriate to use each transport. Also, better-separate concerns in the streamable HTTP transport's implementation.
Fix the OAuth extension to the spec: The OAuth implementation must be revised. MCP servers should be modeled as resource servers only, dropping dynamic client registration.
Improve the ecosystem: Broad client support for the streamable HTTP transport and for the OAuth extension are both needed.
Embrace the full spec: We need to move beyond a "tools only" world and enourage the use of all the powerful primitives that MCP has to offer.

MCP has the potential to be a foundational layer for the next generation of AI applications. but to get there, we need to close the gap between its ambitious promise and its currently broken reality.

Appendix: Other MCP R&D

Check out some of my other work on MCP with Naptha AI here:

the first non-platform-opinionated MCP server that implemented OAuth and the Streamable HTTP Transport shortly after is was approved; which required rewriting parts of the TypeScript SDK to fix broken OAuth code
a fork of Cloudflare's MCP-Remote which supported bridging the Streamable HTTP Transport (not just SSE) to STDIO transports before Cloudflare's did
an early platform for securely deploying SSE MCP servers on the public internet via session keys, before OAuth was added to the specification
a library for wrapping popular agent frameworks with MCP tool bindings so that agents can call other agents as MCP servers, before Google released A2A

Why Everybody's so Excited about MCP

Kyle Mistele — Mon, 07 Jul 2025 16:49:31 +0000

So what even is MCP?

MCP, short for Model Context Protocol, is a protocol designed to enable developers and applications to provide context to agents & large language models (LLMs).
The MCP Specification includes support for a number of different "context" primitives that can be provided to an agent, including prompts, tools, and resources,
as well as a primitive called "sampling" that isn't used much.

Read that, understand that, and then forget that.

The primary use-case for MCP, and the only one that popular MCP clients like Cursor, Windsurf, and Claude code support, is tools.

MCP is about tools

The primary use-case for MCP right now is to plug tools (and therefore new capabilities) into your agents in a low-code, low-configuration way.

Here's an example of my favorite high-impact use-case for software development: Puppeteer's MCP server. By adding a simple JSON configuration to Cursor:

{
    "mcpServers": {
        "puppeteer": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
        }
    }
}

my cursor agent can now drive puppeteer using 7 tools (including tools for navigation, interaction, screenshotting, and eval()-ing JavaScript code).

This unlocks an entirely new development workflow where I can have my agent write UI code, and then use puppeteer to interact with the UI directly.
My agent can iterate on features faster, design and implement UIs better*,
(since the agent can see the actual UI that the code creates, not just the code),
**debug my app significantly faster*, and a lot more.

Notably, without MCP, this would be far more difficult.
The best alternative would be for me to write a bunch of bash or JavaScript or Python scripts to implement these capabilities,
and then update the agent's prompt to inform it of these scripts and how to use them, and then hope for the best.

Other examples

Plugging Puppeteer into Cursor or Windsurf is just one example of a broad and diverse set of use-cases. Consider:

Plugging Claude Desktop or ChatGPT into your Google Docs so that they can create, read and save documents
Enabling agents to manage your Next.js deployments with the Vercel MCP server
Enabling background agents to send you slack messages when they need assistance with the Slack MCP Server
Enabling coding agents to update your GitHub/Linear/Jira issues & tickets as they make progress on issues and to make PRs when they're finished
Enabling voice agents to query your knowledge base without custom code

In all these cases, MCP allows you to plug in arbitrary capabilities to LLMs without having to write custom code to handle the connections, requests, responses, and abstractions.

MCP servers function like no-code pre-built integrations for your agent that give it tools or allow it to access third-party apps and software.

How should you understand MCP?

Given this, how should we understand MCP? Think about it this way:

MCP is a compatibility layer for extending agents & LLMs with arbitrary capabilities in a no-code manner. You can think of it as a special type of API optimized for LLMs.

Now, this isn't entirely accurate as it doesn't cover everything that the MCP specification defines (including sampling), but this is a great mental model for the ways that MCP is actually, presently being used.

MCP vs. Traditional APIs

Let's dig more into this model of MCP servers are LLM-optimized APIs. Consider traditional APIs. They have:

a transport (HTTP)
an interface (usually JSON-based) that provides an abstract model for the underlying resources & capabilities
a set of resources and capabilities that are exposed through that interface
(usually) documentation for humans to read, e.g. a docs site or OpenAPI

APIs then have to be implemented using a HTTP client in deterministic code, which has to be aware of the interface structure, the transport (your code has to set headers, query params, etc.), and all the other details except the actual implemnetation of the capabilities on the API's backend.

MCP optimizes a lot of this for direct consumption by LLMs. Like a traditional API, MCP has:

a transport (which may be STDIO, server-sent events or SSE, a streamable HTTP transport, or WebSockets though it is unofficial)
an interface (JSON-RPC),
and a set of resources and capabilities that they expose.

But while traditional APIs are designed to be consumed by software implemented by developers, MCP is intended to be consumed directly by LLMs & agents,
so there are some significant differences.

The agent isn't aware of the specifics of the transport (no headers or query parameters), and it really isn't aware that the transport exists at all —
it just sends JSON and receives JSON. There are far fewer implementation details to worry about.

The agent may not even be aware it's using MCP — the tools may be presented to it just like normal tools, with names, descriptions, and input schemas.
In this regard, MCP can be thought of as a "self-documenting API". There are pre-determined MCP "API" methods
which list information about the server's resources and about the server's tools (including the name, description, and JSON schema describing the input).
The LLM or agent can use these methods on a connected MCP server to discover the tools and resources that are available to it, and can then intelligently decide
when and how to access or invoke them.

Note on Authorization

Traditional APIs can handle auth however they want - JWTs, HTTP basic auth, API keys, OAuth, or whatever else they want.

MCP now handles authentication & authorization capabilities through OAuth, which allows
users to authorize them to access their applications and data with third-party providers that use OAuth like Google, HubSpot, Linear, etc.

When a user initializes an MCP server for an agent, they may be prompted to authorize access to whatever capabilities and tools the server offers with OAuth, so that they can be exposed to the agent without any type of API key or token.
In practice, this means that when you plug in an MCP server to your client, you will be prompted through a GUI to grant access to the server & agent.

Examples of where you might see this include in a Github or Google MCP server — servers where you are giving the LLM tools to manage remote resources in a third-party service.

This frees you from the complexity of managing API keys, environment variables, and all that.

Why are people excited about MCP?

If you're like me, you've seen dozens of Twitter and LinkedIn posts about how MCP is changing the world.

Well, is it?

No. But it's still pretty great. It has a lot to offer:

MCP for ChatGPT / Claude Desktop users

Non-technical users of ChatGPT, Claude Desktop and other MCP-compatible apps can use MCP to connect their LLM to their local filesystem, to Google Drive/Docs/Sheets/Slides,
Brave search, Obsidian, Notion, the command line, data science tools and Jupyter notebooks, even Google Ads, and more.

It enables them to connect their relatively limited LLM chat, which normally only has acess to web search and maybe code execution, to their favorite apps and tools, unlocking a whole new set of use-cases centered on productivity.

MCP for "Vibe Coders"

MCP is even more popular with "Vibe Coders", who are typically non-technical or low-technical individuals using AI-powered code generation tools like Cursor, WindSurf, Bolt, v0, or Lovable to build apps.

MCP is popular with vibe coders becasueit enables them to upgrade their coding agent's capabilities to be more useful. For example, it could use the Vercel MCP server
to handle setting up their Next.js app for deployment on Vercel, and running deployments and checking logs.

Similarly, they could use a Supabase MCP server to check on their Supabase project and query the database.

MCP for Engineers

MCP is popular with engineers because it allows them to level up their AI-powered coding tools like Cursor, Windsurf, Claude code, and even custom agents or agentic workflows with new capabilities, with relatively little configuration.

I already gave the example of Puppeteer, and there are several more below. For engineers, MCP is a way to make coding agents smarter, more efficient, and more aware of important project context.

Bonus: Cool MCP Servers you should try

As part of doing research for this post, I dug into what the most popular MCP servers are. I found that a lot of them are behind paywalls on Medium, or are
spread out across various registries. In this section, I've put together a list of some of my favorites that are worth checking out.

Context7 — Instant Context & Docs for your Stack

Have you ever used Cursor's Documentation Indexing feature? Imagine having pre-index docs for all your favorite apps and services.
Instead of having to paste URLs, index docs and then @mention them in your agent chat, the Context7 MCP servers allows you to just
ask your agent a question, and tell it

use context7

to answer and it will automatically locate and query the up-to-date docs for whatever you need.

You can find the Context7 MCP server here, and you can install it like this:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Google Ads - Analyze your Google Ads Data with AI

The Google Ads MCP Server is an unofficial MCP server that wraps the google ads APIs and allows you to analyze your
google ads data through natural language. You can install it like this:

{
  "mcpServers": {
    "googleAdsServer": {
      "command": "/FULL/PATH/TO/mcp-google-ads-main/.venv/bin/python",
      "args": ["/FULL/PATH/TO/mcp-google-ads-main/google_ads_server.py"],
      "env": {
        "GOOGLE_ADS_AUTH_TYPE": "oauth",
        "GOOGLE_ADS_CREDENTIALS_PATH": "/FULL/PATH/TO/mcp-google-ads-main/credentials.json",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "YOUR_DEVELOPER_TOKEN_HERE",
        "GOOGLE_ADS_LOGIN_CUSTOMER_ID": "YOUR_MANAGER_ACCOUNT_ID_HERE"
      }
    }
  }
}

Note that this server requires some more technical information to successfully configure.

Puppeteer: Let Your Agent Drive a Web Browser

My personal favorite server allows my Cursor agent to drive Puppeteer, a browser automation framework.
I love this server because it enables the agnet to navigate my apps as I'm building them, to interact with
them, and to take screenshots.

This rapidly speeds up the development cycle because the agent can see features and interfaces as it's building them,
and it can interact with them to test, validate and debug them.

You can install the server here


{
    "mcpServers": {
        "puppeteer": {
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
            "env": {
                "PUPPETEER_LAUNCH_OPTIONS": "{ \"headless\": true}",
                "ALLOW_DANGEROUS": "true"
            }
        }
    }
}

Note that if you want the agent to be able to drive your browser with all of your cookies and sessions (which is useful for apps with auth),
you can set another environment variable with the path to your chrome data directory. This path is different depending on your OS, but for my Macbook it looks like this:

"CHROME_USER_DATA_DIR": "/Users/kyle/Library/Application Support/Google/Chrome/Default"

Docker: Let Your Agent Manage Your Containers

This server is really useful for docker- and Docker compose-based projects. Instead of making your agent write shell commands,
it gives your agent an easier way to manage docker and compose. I use this one a lot. You can install it here
like this:

{
    "mcpServers": {
        "docker": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/ckreiling/mcp-server-docker",
                "mcp-server-docker"
            ]
        },
    }
}

Postgres: Enabling your Agent to Safely Query your Database

I work with postgres a lot whether through Supabase, Docker, AWS, or other servers. This one is really useful for me:

{
    "mcpServers": {
        "postgres": {
            "command": "bunx",
            "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://postgres:YOUR_PASSWORD_HERE@pgvector:5432/postgres"]
        }
    }
}

Note that you need to make sure to not commit this to GitHub, unless you use another way of configuring your credentials!

Stripe: Connect your Agent to your Stripe Account

If you're building a SaaS app and are using Stripe for billing, this is a great one to use:

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
          "-y",
          "@stripe/mcp",
          "--tools=all",
          "--api-key=STRIPE_SECRET_KEY"
      ]
    }
  }
}

Just like above, make sure to not commit this to Git!

Supabase — Connect your Agent to your Supabase Project

Lots of developers love Supabase's open-source platform for everything from postgres hosting, to object storage, to pub-sub and even auth.
If you use Supabase for your projects, using their MCP server is a no-brainer!

This server enables you to query your database and project in natural language. Super useful!

Here's how you can install it:

{
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": [
        "-y",
        "@supabase/mcp-server-supabase@latest",
        "--read-only",
        "--project-ref=<project-ref>"
      ],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "<personal-access-token>"
      }
    }
  }
}

Zapier — Connect your Agent to Thousands of Apps

If you're a Zapier user, this server is for you!
Zapier's MCP server empowers your agent to use the apps and workflows you have connected in your Zapier account!

This is a great way to integrate your agent with any of thousands of applications with a single MCP server, with no code!
Just configure apps in your Zapier account, plug in your Zapier MCP server, and you're good to go!

Conclusion

Ultimately, the best way to understand the excitement around MCP is to think of it as a specialized plug-and-play API for adding capabilities to LLMs.
This simple mental model captures its core value: it allows anyone, from non-technical professionals to seasoned engineers, to easily extend their AI agents with
powerful new tools and capabilities.

By providing a no-code integration and compatibility layer, MCP makes agents more capable and useful for everyone today.

Footnote: I do not recommend using MCP for production agents and agentic workflows. I'll cover this in another post.

The OAuth Integration Nightmare: 8 Critical Components you'll need to build

Kyle Mistele — Mon, 23 Jun 2025 15:07:43 +0000

The OAuth Challenge

I recently spent several weeks implementing OAuth flows for an OAuth-related project, and I was struck by how much complexity is hidden beneath the surface. What looks like a simple authorization flow in theory requires building and maintaining at least eight distinct components - and many of these components differ for each OAuth provider you want to support.

In this article, I'm going to walk you through the surprisingly complex world of OAuth integrations. If you've ever tried to implement an OAuth flow from scratch, you know it's not as simple as the diagrams make it seem. There are numerous moving parts, security considerations, and provider-specific quirks that can make this seemingly straightforward task a genuine headache.

Worth clarifying: in this article, I'm not concerned with using OAuth (or more specifically OpenID Connect, also known as OIDC) for user authentication – that can be easily handled with solutions like Better Auth and similar. What I'm concerned with is actually building integrations with OAuth apps so that you can use their APIs to do things, like sending messages in Slack or retrieving documents from Google Drive.
There are a different set of considerations that these types of integrations imply.

Also, for the purposes of this article, we're primarily concerned with the OAuth Authorization Code Flow. There are other OAuth flows like the Implicit Flow, but this is the one that you will most-commonly use as it is more secure than the implicit flow.

Let's break down these components one by one, and I'll share some code examples and lessons learned along the way.

Overview the Authorization Code Flow

Before we get into the components you'll need to build, let's do a quick overview of the Authorization code flow. Generally, there are five entities that are party to an Authorization code flow:

The user
The user's browser
Your application
The OAuth Authorization server that handles granting tokens
The Resource server which the authorization server's tokens grant access to

Now, don't worry if you don't know what all the terms here are - we'll get to them below! Here's how it works:

Access (User) – Ther user clicks a button in your app that's in their browser to initiate the OAuth flow to connect an app
Request Authorization (Your application) – Your app generates a URL to the Authorization server's authorization endpoint which includes a bunch of information including your client ID, a redirect URL, the response_type set to code to indicate we're using the Authoriztaion Code flow, and the requested scopes – along with other optional fields like state, or provider-specific fields. The user is redirected to this URL at the authorization server in their browser, which requests authorization from the authorization server
Display Consent (Authorization Server) – The authorization server (e.g. Google's OAuth server) will ask the user if they want to authorize your app (identified by its client ID) to access whatever permissions and resources are specified by the scopes.
Give Consent (User) – The user can give consent for (authorize) your app to access the requested resources identified by the scopes by clicking a button.
Issue Authorization Code (Authorization server) – The Authorization server will redirect the user's browser to your applications's redirect URL with either query parameters including a code which is the Authorization code and the state specified in step (2), or an error indicating that an error occured. Note that the authorization code is an opaque token.
Request Access Token (your application) – Once your application receives the authorization code (and the state), it should make a POST request from the backend to the Authorization server's token endpoint with your application's client ID and client secret, the authorization code from the previous step, the original redirect URL, and optionally other provider-specific fields.
Issue Access Token (Authorization server) – If everythign is in order your application will receive a response containing at minimum an access_token and a token_type. It may also receive an expires_in field (in seconds, not milliseconds) denoting when the access token expires, and a refresh_token which does not expire, which may be used to obtain a new, unexpired access token.

The access token can then be included in requests from your application to a resource server which trusts the authorization server (e.g. how the Google docs API trusts the Google OAuth authorization server) to take actions which are authorized by the scopes which were granted after being requested.

The 8 Critical Components of OAuth Integrations

With this understanding in mind, let's break down what you actually have to build in order to ship an OAuth integration.

1. Client Credentials Management

Every OAuth integration requires a client ID and client secret. There's simply no way around this unless you're using someone else's credentials (which, as I'll explain, is a terrible idea).
The Client ID and Client Secret are collectively referred to as your "Client Credentials".

I've seen some developers use integration platforms like Pipedream or Composio that let you use their OAuth credentials. This is a recipe for disaster. If their credentials get compromised or restricted (perhaps because another user on their platform is misbehaving), your application will suddenly stop working. Always get your own client credentials.

Usually, you can do this from your OAuth Provider's dashboard, for example under "OAuth Applications" which is under "Developer Settings" under your profile settings in Github, or under the OAuth Apps section of the Google Cloud dashboard.

Some providers will require additional configuration once you obtain your app and create your client credentials. For example, Slack makes you configure at least one scope.

Once you have these, you'll need to pass them to your application. Using a dedicated secrets manager is the best option, and using environment variables is next-best. But never, ever hard-code these values in your source code or track them in version control.

// BAD:
const GOOGLE_CLIENT_ID = 'abcdef'
const GOOGLE_CLIENT_SECRET = 'xyz123'

// BETTER:
const { GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET} = process.env

// BEST:
// (prevent downstream errors from missing values):
const requireEnvironment = (variableName: string): string => {
  const value: string | undefined = process.env[variableName]
  if (value) return value
  const msg = `Environment Variable ${variableName} is not in the process environment!`;
  console.error(msg)  // capture this in logging and telemetry.
  throw (err)         // we treat this as an un-recoverable error. 
}

const GOOGLE_CLIENT_ID = requireEnvironment('GOOGLE_CLIENT_ID')
const GOOGLE_CLIENT_SECRET = requireEnvironment('GOOGLE_CLIENT_SECRET')

2. Building a Callback URL Handler

When you redirect users to the provider's authorization URL, they'll eventually be redirected back to your application with an authorization code. You need to build an endpoint to handle this callback.

Note that you should probably start by defining the route in your app but stubbing out the contents so that you can configure the URL in the OAuth provider's dashboard as a valid redirect URL for your application, since most providers require you to provide a whitelist of these.

import express, { type Request, type Response, type NextFunction } from 'express';


interface OAuthCallbackQueryParams {
  code?: string;
  state?: string;
  error?: string;
}

interface OAuthTokenResponse {
  access_token: string;
  token_type: string;
  refresh_token?: string;
  expires_in?: number;
}

app.get('/oauth/callback/google', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const { code, state } = req.query as OAuthCallbackQueryParams;

    // Verify state to prevent CSRF (more on this later) and load other information from the state.
    if (!await verifyOAuthState(state)) {
      return res.status(400).send("Invalid state parameter");
    }

    // Exchange the code for tokens (next step)
    const tokens: OAuthTokenResponse = await exchangeCodeForTokens(code!);

    // Store tokens securely
    await storeTokensForUser(req.user.id, tokens);

    return res.redirect('/dashboard');
  } catch (error) {
    console.error('OAuth callback error:', error);
    return res.status(500).send('OAuth callback failed');
  }
});

Note that aside from the error or state and code parameters, some OAuth providers will include additional parameters.

3. Initiating the OAuth Flow

Once you have a callback / redirect URL to receive the Authorization Code from the authorization server, you can initiate the OAuth flow for a user by redirecting the user to the Authorization Server's authorization URL with your client ID, redirect URL, list of requested scopes, and state value.

Some providers require or allow you to add additional query parameters with their own semantics (like Google).

const baseUrl = 'https://accounts.google.com/o/oauth2/v2/auth'

// the redirect URI must be an absolute URL
const redirectUri = `${requireEnvironment('APPLICATION_BASE_URL')}/oauth/callback/google`

// Scopes are usually things like 'channels:read' but other providers treat them like URLs. 
const scopes = [
  'https://www.googleapis.com/auth/drive',
  'https://www.googleapis.com/auth/drive.file'
]

// Optional; more on this later.
const state = generateState(userId)

const url = new URL(baseUrl)
url.searchParams.set('client_id', clientId)
url.searchParams.set('redirect_uri', redirectUri)
url.searchParams.set('state', state)

// Denotes authorization code flow
url.searchParams.set('response_type', 'code')     

// Some providers use space-separation, others use `+` or `,`
url.searchParams.set('scope', scopes.join(' ')) // Use space separation for Google OAuth

// Google-specific fields
url.searchParams.set('access_type', 'offline') // Request refresh token
url.searchParams.set('prompt', 'consent') // Force consent to ensure refresh token

const authorizationUrlForUser = url.toString()

Once you have an authorization URL for the user with all the correct query parameters, you should redirect the user to it.

URL construction will vary for each provider depending on their base URL, scope separation conventions, and any additional required or optional query parameters.

4. Authorization Code Exchange

Once the user is redirected to the authorization URL and grants consent, they will be redirected back to that callback URL / redirect URL with the state parameter you specified, and the code (the authorization code).

Once you have the authorization code, you need to exchange it for an access token.

const GOOGLE_CLIENT_ID = requireEnvironment('GOOGLE_CLIENT_ID')
const GOOGLE_CLIENT_SECRET = requireEnvironment('GOOGLE_CLIENT_SECRET')

interface GoogleTokenResponse {
  access_token: string;
  refresh_token?: string;
  expires_in: number;
  token_type: string;
  id_token?: string;
}

async function exchangeGoogleAuthCode(code: string, redirectUri: string): Promise<GoogleTokenResponse> {
  try {
    const data = new FormData()
    formData.append('grant_type', 'authorization_code')
    formData.append('code', code)
    formData.append('redirect_uri', redirectUri) // the origiunal redirect URI you specified in the authorization URL
    formData.append('client_id', GOOGLE_CLIENT_ID)
    formData.append('client_secret', GOOGLE_CLIENT_SECRET)


    const response = await fetch('https://oauth2.googleapis.com/token', {
      method: 'POST',
      body: formData,
    })

    const {
      access_token,
      expires_in, 
      refresh_token,
      token_type,
      ...metadata
    } = await response.json()

    // Note: you will want to save all of this information
    await saveAllThisInformation({access_token, expires_in, refresh_token, token_type, metadata})

    // TODO - something that makes sense for your application. redirect them to the dashbord and show a toast or something.
  } catch (error) {
    console.error('Error exchanging auth code:', error);
    throw error;
  }
}

Here's an example of making that request in cURL for the non-typescript users:

curl -X POST https://oauth2.googleapis.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "code=YOUR_AUTH_CODE" \
  -d "client_id=YOUR_GOOGLE_CLIENT_ID" \
  -d "client_secret=YOUR_GOOGLE_CLIENT_SECRET" \
  -d "redirect_uri=https://your-app.com/oauth/callback/google" \
  -d "grant_type=authorization_code"

There are lots of "gotchas" here:

Content types: different OAuth providers will require & support different content types for token exchanges (and token refreshes). The most common one, shown in the specification, is application/x-www-form-urlencoded. However, some providers support / require other formats, including application/json and multipart/form-data. When I was implementing this flow for a number of different OAuth providers, I ran into all three of these for request content types, though most by default returned responses as application/json. But watch out for this! Each provider may do it differently
Access token lifespan: at a minumum, an OAuth provider should return an access_token and token_type field, named as such. If this is all you receive, it's often the case that the access token doesn't expire. If the access token expires, the provider may also return an expires_in field (in seconds, not milliseconds! That's a common gotcha.) and optionally a refresh_token which is a long-lived or non-expiring token that can be used to obtain a new access token once the current one expires. Some providers like Linear issue super-long-lived access tokens (e.g., 10 years), effectively punting on the refresh token mechanism.
Additional content: Many OAuth providers will provide additional fields that contain provider-specific metadata, or things which pertain to various OAuth extensions.

All of these need to be handled correctly on a per-provider basis!

5. Token Refresh Management

Most access tokens expire, which means you need to track when they expire and refresh them when needed. This requires storing refresh tokens securely and implementing a token refresh mechanism.

Usually, refreshing an access token involves making a POST request to the same token endpoint as in the token exchange, and requires providing your Client ID, Client Secret, the grant_type set to refresh_token, and the refresh token for the user whose access token you want to refresh. In most cases, providers use the application/x-www-form-urlencoded content type, but your mileage may vary as previously noted. Make sure to consult the docs.

// TypeScript example for token refresh
interface RefreshTokenRequest {
  refresh_token: string;
  client_id: string;
  client_secret: string;
  grant_type: 'refresh_token';
}

interface RefreshTokenResponse {
  access_token: string;
  expires_in: number;
  refresh_token?: string;
  token_type: string;
}

async function refreshGoogleAccessToken(refreshToken: string): Promise<{
  access_token: string;
  expires_in: number;
  refresh_token?: string;
}> {
  try {
    const params = new URLSearchParams({
      refresh_token: refreshToken,
      client_id: requireEnvironment('GOOGLE_CLIENT_ID'),
      client_secret: requireEnvironment('GOOGLE_CLIENT_SECRET')
      grant_type: 'refresh_token'
    });

    const response = await fetch('https://oauth2.googleapis.com/token', {
      body: params.toString(),
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      }
    })

    const { 
      access_token, 
      expires_in, 
      token_type, 
      refresh_token
    }: RefreshTokenResponse = await response.json()
    // todo: save this information!
  } catch (error) {
    console.error('Error refreshing token:', error);
    throw error;
  }
}

# cURL example for Google OAuth token refresh
curl -X POST https://oauth2.googleapis.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_GOOGLE_CLIENT_ID" \
  -d "client_secret=YOUR_GOOGLE_CLIENT_SECRET" \
  -d "grant_type=refresh_token"

You can either proactively refresh access tokens as soon as they expire, or you can refresh them on-demand when a user needs them and you find that they're expired – just know that doing so will create additional latency.

Once again, different OAuth providers handle this exchange differently. Some give you only access_token and expires_in and token_type. Others will give you a new refresh token as well, depending on additional fields you can add to the request.
Still others will give you additional metadata.

6. Scope Management

When your application requests user authorization, it must provide a list of scopes that it is asking for to the Authorization Server in the scope query parameter to the authorization URL. Usually, you will specify a list of scopes as a single string, concatenated by spaces, commas, + signs, or something similar.

There are no "standard scopes" in OAuth - the list of possible scopes you may request depends completely on the OAuth provider and their services and system architecture. (There are, however, standard scopes for OpenID Connect).
Some OAuth providers' scopes look like simple words: channels, emails, etc.

Others are more narrow and hierarchical: channels:read, im:read, im:write, and so forth.

And still others model them as URLs: https://www.googleapis.com/auth/drive.file, https://www.googleapis.com/auth/cloud-platform.read-only

Your application needs a list of the scopes that you want to request from the provider when you initiate the OAuth flow.

Based on the scopes you're requesting, the Authorization server will usually display information about what privileges you're requesting (which are entailed by the scopes) to the user on the consent prompt.

Some providers then only give the user the option to approve or reject the authorization request. Others will allow the user to check boxes or otherwise select which permissions that you have requested they would like to grant. Still others allow you to specify a list of "required scopes" that your app needs to function, and "optional scopes" that you would like but which the user can choose not to grant while still authorizing your app for the required scopes.

In these cases, the provider may return to you a list of scopes (in their own format, providers don't really follow a standardized way of doing this) in the response to the access token exchange or token refresh request, that indicates which scopes out of the ones that you requested your access token has actually been granted.

In these cases, depending on your application, you may need to track which scopes you have been granted and which APIs / resources you are and are not able to use on the resource server based on the granted scopes.

Obviously, this can get messy quickly when you're implementing lots of different providers.

7. State Parameter and CSRF Protection

So earlier, we mentioned but skipped over the state parameter. "What is it, and why should I care about it if it's optional?", you might ask.

Great question. The state parameter is a **security feature which is used to prevent Cross-Site Request Forgery (CSRF) attacks, and which providers other benefits:

Purpose & Functionality:

CSRF Protection:
- When your application initiates the authorization code flow, the backend should generate a unique, random (sufficiently-long so as to be secure) state value, and include it in the authorization server URL redirect.
- The state value should then also be set as a CSRF cookie (make sure to set the SameSite property to lax! Otherwise it won't work since Cookies with a strict SameSite property aren't included on requests that result from cross-domain redirects; which the callback is)
- The authorization server will include that same state value as a query parameter in the redirect to your callback URL after the user grants consent.
- Your callback URL handler should verify (a) that your server issued this state value, and (b) that the value in the URL matches the value in the CSRF cookie.
- If they don't match, the client should reject the response, to prevent unauthorized or tampered-with responses and session hijacking attacks.
Session Correlation:
- When your application creates a state value, it can store it in the database and associate it with the currently-authorized user, and with other relevant information.
- The state value can then be used to correlate the callback with the initial redirect to the authorization URL. This is useful in scenarious where there are multiple users or sessions in the same brrowser at the same time.
- It can ensure that the response is processed in the context of the correct user session.
Optional Data:
- in your database , you can associate information with the token such as the URL in your application that you want the end-user to be redirected to after the callback is processed.
- it can be used to maintain other application context; however it should be an opaque token since it may be exposed in logs.

How it works:

Your application securely generates the state value on the backend before redirecting the user to the Authorization Server's authorization URL.
(Optional) Your application may store the token in its' database with optional contextual information as mentioned above.
Your application should set it as a cookie in the user's browser before redireting them to the authorization server's authorization URL.
Your application should include the value as the state query parameter on the authorization URL that the user is redirected to.
When your users receives the callback redirect from the authorization server, check the state value to confirm that it's present, and that it matches the contents of the cookie you set.
(optional) retrieve contextal application information and use it

Generally, you should follow the following best practices for state:

Unique: The state value should be unique for every authorization request
Random: It should be securely random - i.e. of sufficient length and complexity that it is infeasible to guess.
Secure storage: Set the state value as a HttpOnly cookie (make sure to set SameSite to lax - strict won't work!)
No sensitive data: Avoid including any sensitive information in the token itself - any application-specific contextual information should be stored in the database in a manner that's assoicated with the token. Don't use signed JWTs or something which may expose information.
Always use it: While the state parameter is an optional part of the specification, it's strongly recommended to use it to enhance your application's security.

8. Secure Token Storage

Using access tokens for user authentication through a library like Better-auth where you're requesting non-highly-sensitive scopes like openid, email, and profile through OpenID Connect is one thing. You should still care about these tokens (they give you PII!), but you would be storing these unencrypted in your database.

But if you're building OAuth integrations, in many cases you're doing it so that your application can access your users' information in other systems – things like files, emails, contacts, or accounting and payroll information, financial information, CRM, helpdesk tickets, or other software systems.

In these cases, you should think of access tokens as API Keys that give you access to sensitive information, resources, and systems on the user's behalf. The security considerations of this model are completely different from user authentication with OpenID Connect.

Similarly to how you (hopefully) wouldn't store your users' passwords or API keys unhashed in a database, you shouldn't store your users' sensitive access tokens unencrypted.

Now you may be thinking, "My database provider users encryption-at-rest! I'm already doing this."

And you would be wrong

Unless your threat model is someone walking into your cloud provider's datacenter and pulling out the hard drive that your database lives on and walking out with it, encryption at rest is security theatre. Encryption at rest does not prevent most database compromises, and does not secure information from software hacks.

So what should you do? The simple answer is field-level encryption - securely encrypt access tokens before inserting them into the database, and decrypt them after you retrieve them from the database when you need to make an API call. Here's a great example of how to do this with Drizzle ORM, which can be generalized to other frameworks and languages.

This will prevent someone who gets access to your database from stealing all of the access tokens, unless they are able to separately compromise your application's encryption key.

Personally, I really like using Evervault - they have a great drop-in relay-based solution that requires minimal code changes (just an encrypt-only API key and relay URLs) and which means that you don't ever have to manage keys. Evervault manages keys and encryption/decryption operations, while you manage business logic and encrypted data.
This separation of concerns means that even if your application is entirely compromised, an attacker can't decrypt your data, since all they would get is encrypted data and an encrypt-only API key. And if evervault were compromised, the attacker would only get keys - not encrypted data. You would both have to be compromised for your data to be stolen.

(Note: I do not work for Evervault, and this is not a paid promotion - I just really like their solution!)

Conclusion

Building OAuth integrations is significantly more complex than it initially appears. You need to implement and maintain at least eight distinct components, many of which differ for each provider you support:

Client credentials management
Callback URL handling
Initiating the OAuth flow
Authorization code exchange
Token refresh management
Scope management
State parameter and CSRF protection
Secure token storage

This complexity is why many developers turn to OAuth libraries or integration platforms. However, even with these tools, you still need to understand the underlying mechanics to debug issues and ensure you're implementing everything securely.

Have you implemented OAuth in your applications? What challenges did you face? Let me know in the comments below!

P.S.: we built One Dollar OAuth to solve all of this complexity for you for just $1 per application! Check it it out at OneDollarOauth.com.